ASP.NET Core Web/API Engineering

A working POST can still be the wrong API

The orders demo looks convincing: POST /orders returns an order, and GET /orders/2 reads it back. Then an unauthenticated request creates another order. A validation failure arrives as 200 with an error string. Retrying a timed-out POST creates two orders. The happy request worked; three different promises failed.

You will build the ASP.NET Core API Contract, Failure and Verification Matrix v1: an explicit relationship between routes, schemas, permissions, failures, duplicate requests, documentation and observed cases. The aim is to explain which API slice the evidence supports and what prevents a stronger claim.

Allow 60 active minutes: 10 for the foundation, 15 for the worked cases, 15 for guided diagnosis, 15 for PATCH transfer and 5 to defend your decision. The core requires Python 3.10+ and supplied JSON/CSV, with no external packages. pipeline_demo.py actually executes an in-process Python model using synthetic requests. It opens no network port, validates no real token and does not execute ASP.NET Core. C# excerpts explain the corresponding framework boundaries; they are not a buildable project or an execution receipt.

For readers returning to .NET who can read C# and asynchronous calls but need a deliberate, testable Web/API boundary.

This lesson does not implement production identity, database migrations, a background-worker platform or deployment readiness. Those require their own evidence.

Choose your entry point

NET-001 is the required foundation and previous educational lesson. NET-003 follows with data access. The hosting and diagnostics outcome belongs to NET-004; finishing this API matrix does not finish that outcome.

Distinguish a nullable DTO property from an optional JSON member. Explain what await waits for, who owns a scoped dependency, and why an exception is not automatically a suitable HTTP response.

A DTO describes data crossing a boundary; it need not be the stored entity. Binding constructs values from a request, while validation decides whether those values are acceptable. A dependency performs work on behalf of the handler. Await that work within its lifetime. An error handler converts selected failures into a public response. Recheck by explaining why a syntactically valid quantity of zero can bind successfully and still fail the order rule.

Foundation route: read the field map and follow both examples before opening the lab. Repair route: locate the first broken promise, then retain every additional cause until repaired. Experienced route: inspect the tradeoffs and go to practice. Each route submits the same matrix, negative evidence and changed-context transfer.

Separate the promise, implementation and observation

An HTTP contract says what clients can send and receive. A pipeline orders routing, identity, permission checks, binding and handler work. An OpenAPI document describes operations and schemas. A test observation records one execution under a specific host and configuration. None substitutes for the others.

A documented POST can lack enforced authorization. A correctly protected POST can have stale documentation. A test can call the handler directly and bypass the middleware whose behavior it purports to prove. Ask “which boundary did this observation cross?” before asking whether it passed.

The flow's text equivalent is: define the requirement and HTTP contract; inspect authentication, authorization and validation; bind the candidate implementation; generate and compare OpenAPI; execute a named test host with happy and negative cases; inspect responses and side effects. Missing or stale evidence means HOLD. Contradiction means repair and rerun while keeping HOLD. Complete evidence permits VERIFIED_SYNTHETIC only within SYNTHETIC_ONLY, never framework or deployment approval.

NET-002-F1 — Boundary retrieval. Name the difference between an OpenAPI path and an enforced permission. Give one observation that a direct handler call cannot establish. If you treat either as proof of the whole pipeline, return to the four records above.

Read the matrix before the result

The complete 22-column NET-002-T1.csv has one row per baseline case. field_map.json explains how each column is derived from the visible fixture; integration_test_case is a model case identifier, not a claim that an ASP.NET integration test ran. The compact worked table is a reading aid, not a replacement for the full artifact.

UNKNOWN means a decisive input is unknown. UNVERIFIED means evidence has not established a claim; UNSUPPORTED means a contract or environment cannot support it. STALE identifies evidence from the wrong context or time. FAILED records a contradicted expectation; REVIEW_REQUIRED keeps a decision open. All unresolved critical dimensions yield HOLD. These states do not become success by averaging them against nineteen green checks.

A negative request can pass its test: rejecting an unauthenticated POST with the declared challenge and no write is the expected result. That is different from the API unexpectedly accepting it.

Build the boundary deliberately

DTOs, binding and validation

The exercise POST accepts exactly customerReference and integer quantity. Missing or extra members, malformed JSON and a string quantity receive 400; an unsupported media type receives 415. A nonblank reference of at most 40 characters and quantity 1–20 are domain rules; a syntactically valid violation receives 422. These are explicit exercise choices. They are not all ASP.NET defaults.

For example, { "customerReference": "desk-7", "quantity": 0 } reaches domain validation but cannot create an order. The string "2" is a different binding case. Reference length counts the original JSON string, including leading/trailing spaces; a short accepted reference is stored unchanged, and whitespace-only text is rejected. Unknown members are rejected by our model; configure and test the serializer separately if you require that behavior in C#.

ASP.NET Core 10 supports validation for Minimal APIs through AddValidation; controllers with [ApiController] provide automatic model-validation responses. The controller default is 400, not our custom domain 422. Decide whether framework validation or explicit handler logic owns each rule and test the resulting response. Validation, Controller APIs

A C# DTO can express the transport shape:

public sealed record CreateOrderRequest(string CustomerReference, int Quantity);
public sealed record OrderResponse(int Id, string CustomerReference, int Quantity);

These declarations alone do not reject every malformed or semantically invalid request. In a separately configured project, explicit domain validation might return Results.Problem(statusCode: 422, title: "Order validation failed"). Our full problem-body policy additionally requires type, instance and trace identity; a short snippet is not evidence those fields were configured.

Authentication precedes permission and work

Authentication establishes a caller identity; authorization determines allowed actions. This slice requires Orders.Read for GET and Orders.Write for POST/PATCH. An unauthenticated request gets 401 with WWW-Authenticate: Bearer; an authenticated principal lacking permission gets 403. Those are our declared cases. A test must check no write occurred before rejection. Minimal API security, HTTP semantics

In an already configured bearer-authentication project, registering and applying a policy are separate actions:

builder.Services.AddAuthorization(options => {
    options.AddPolicy("Orders.Write", policy => policy
        .RequireAuthenticatedUser().RequireClaim("permission", "Orders.Write"));
});
// After building app; CreateOrder is the project's handler:
app.MapPost("/orders", CreateOrder)
    .RequireAuthorization("Orders.Write")
    .Produces<OrderResponse>(201)
    .ProducesProblem(422);

Repeat the appropriate declaration/application for the read operation. Metadata methods describe expected responses; they do not implement validation. A secure production authentication handler must validate credentials and establish claims. The Python exercise instead receives a labelled synthetic principal in memory; never expose that mechanism as a client-controlled authentication header.

The observed model trace is exception handler → routing → authentication → authorization → binding → validation → handler. Rejection stops later work. This trace explains the exercise, not every possible ASP.NET filter or middleware arrangement. In a real application, verify the actual configured pipeline and exception coverage, not the names written in a metadata list.

Errors are part of the response contract

404 covers the selected missing-order case; 409 represents reusing one idempotency key with a different request; 500 represents an unexpected dependency failure. A 200 body containing an error message lies about our contract. Test HTTP status, content type, body and effects together.

AddProblemDetails registers problem-details support; exception handling and status-code middleware use it under their configured conditions and content negotiation. They do not turn an already written 200 error body into the intended failure response. Test with supported JSON Accept headers. API error handling

Our fixed safe body requires type, title, status, instance and traceId, with HTTP/body status agreement and no private exception data. This exact required-field set and whitelist are exercise design, not a claim that RFC 9457 universally requires all five. Problem Details allows extensions; our trace identifier is one. Problem Details specification

A header does not make POST idempotent

Our policy scopes the key to caller, method and path and binds it to canonical parsed request JSON. A first valid request creates one order. A repeat with the same key and payload returns the original 201, body and Location with no additional write. A changed payload under that key returns 409. Another caller has a separate key space. The concurrent duplicate case must still produce only one order.

api_model.py protects lookup, creation and replay recording in one process lock. This is an actual, limited mechanism; it loses its map on restart and coordinates no other process. It establishes neither durable idempotency nor exactly-once external effects. A real design must define storage, retention, crash recovery and coordination together. POST is not automatically idempotent, and idempotence generally concerns the intended effect, not identical responses in every API. Our replay response is a local policy. HTTP method semantics

Compare documentation and executed cases

In ASP.NET Core 10, the built-in OpenAPI package supports generation through AddOpenApi and MapOpenApi; the .NET 10 default document family is OpenAPI 3.1. Keep the documentation endpoint's exposure deliberate. Generating a path or security declaration does not enforce the endpoint's permission. ASP.NET OpenAPI

Our generator writes an OpenAPI 3.1.1 snapshot from Python metadata. Inspect request schemas, success and problem responses, required key header and security for each operation, then compare the snapshot with its bound implementation. It is not output from Microsoft's generator and does not claim full OpenAPI conformance certification. OpenAPI 3.1.1

For real framework evidence, a prepared test project can use WebApplicationFactory<Program> and an HTTP client through the test server. Disable automatic redirects when checking rejection, install an explicit test authentication handler, and substitute a disposable dependency. Exercise requests through that host instead of calling handlers directly. Such tests still do not verify a real token issuer, TLS, reverse proxy or deployment. ASP.NET integration tests

Work two cases from their evidence

Download the learner lab, open the learner folder and run:

python pipeline_demo.py
python generate_openapi.py implementation.baseline.json openapi.rebuilt.json
python run_checks.py --inventory

The model executes 19 baseline cases, including a concurrent pair. Each case starts from one seed order; multiple requests inside the same case share that case's state. Read contracts.json for requests and declared expected responses, then compare actual output with fixtures/baseline.json. Expected values are a test specification, not an observation.

Example 1: baseline. Identify CreateOrder, POST and /orders, then the CreateOrder/Order schemas. Compare all declared statuses and the validation rule. Inspect the unauthorized, forbidden, replay, changed-key-payload and dependency-failure cases, not only the first row. The contract digest matches the selected profile; the implementation digest matches the candidate metadata; model source, document and captures share the required identities. Review is synthetic and current on 2026-09-12. Its context_id, contract_digest, implementation_digest and test_host_source_sha256 match this context, selected profile, candidate metadata and model source. A missing or mismatched review association is CONTEXT_STALE / STALE, even when its owner and capture_ref are present. All visible rules support VERIFIED_SYNTHETIC in SYNTHETIC_ONLY. They do not support “ASP.NET ran.”

Example 2: authorization removed. In authorization_removed.json, /implementation/endpoints/1/authorization_policy is empty while the document still contains the POST path. The policy violation is AUTHORIZATION_GAP with FAILED; implementation disagreement is also FAILED. Old captures produce CONTEXT_STALE, and the old document produces OPENAPI_STALE, both STALE. The complete code set is AUTHORIZATION_GAP, CONTEXT_STALE, IMPLEMENTATION_MISMATCH, OPENAPI_STALE; aggregate HOLD.

The minimal repair is to restore the required policy on the intended endpoint, bind the corrected candidate, regenerate the document and rerun affected positive and negative cases, then review that context. Editing old capture digests is not rerunning tests. Use pipeline_demo.py --fixture fixtures/authorization_removed.json --case post_unauthenticated to observe why the altered model is unsafe. The fixture's copied historical capture and this fresh counterexample answer different questions; preserve both.

Diagnose the failed promise

error_as_200 changes the observed invalid-order response into successful HTTP status with an error string. It violates response semantics even if the string is helpful. schema_drift changes a required request member while retaining old documentation and captures. idempotency_missing removes the declared replay mechanism. missing_capture has a PASS label without a usable capture reference. None deserves success based on labels alone.

auth_side_effect records a write during an unauthenticated request. Checking only 401 would miss the effect. error_disclosure adds a synthetic private stack marker to a failure body: even a correct 500 cannot justify exposing it. Check nested bodies and preserve every cause. stale_review is past its stated review date; past evidence stays historical rather than silently becoming current.

NET-002-F2 — Negative-case diagnosis. For error_as_200, identify the response field that contradicts the contract, name the consequence for a client, and describe the smallest repair plus the case that must run again. Return to error semantics if your repair changes only the message text.

Some causes overlap deliberately. A failed replay observation can contradict both response behavior and idempotency. Keep both dimensions: one explains the public result, the other the duplicate-effect promise. The grader checks the complete known cause set; a correct aggregate with omitted causes is incomplete.

For experienced .NET readers

A controller action returning the expected object does not establish the behavior of an entire host. Identify which filters, model validation, authentication handlers and exception middleware a test traverses. Moving from controllers to Minimal APIs changes where conventions and validation are configured; mechanically moving the handler does not preserve every response.

Read the exercise identifiers literally. implementation_digest hashes canonical metadata JSON, not compiled assemblies or the C# excerpts. test_host_source_sha256 binds the executed Python source. contract_digest hashes the selected profile, while submission-level contracts_sha256 binds the complete public specification, including case expectations. These hashes establish association and change detection, not truth or reviewer authority.

The model route matcher accepts a deliberately bounded nonnegative digit path; it is not a conformance test of ASP.NET's int constraint, overflow, URL decoding or all routing precedence. Its principal, store and timeout switch are test devices. To make a real ASP.NET claim, replace the model-only evidence with actual host/configuration, generated-document and HTTP-test receipts. Preserve the model's educational result as a separate record.

Choose style and mechanisms for this slice

Both Minimal APIs and controllers are supported approaches. The choice is about the application's organization and testable contract, not a universal performance verdict. We choose Minimal API metadata for a two-operation baseline and keep the policy explicit. Minimal API overview

Choose the error contract before copying a convenience return helper. Decide whether a dependency failure can occur before or after an effect, because a status alone cannot undo work. If the evidence leaves that distinction unknown, retain UNVERIFIED and request the specific failure observation; do not invent a compensating transaction.

Practice, then change the contract

First generate your guided submission:

python run_checks.py --template fixtures/error_as_200.json submission.json --as-of 2026-09-12
python run_checks.py --check fixtures/error_as_200.json submission.json

Between these commands, fill the decision, typed issues, JSON pointers, rationale, minimal repair and review trigger. The template binds input, policy, complete contracts and date but leaves the answer empty; it does not overwrite an existing file. STRUCTURE_PASS_SEMANTICS_UNREVIEWED means only that the submission shape and references are valid. Semantic correctness and explanation still require review. Work the remaining mutations independently with separate submission names. Preserve original inputs.

Transfer: PATCH and a background dependency. transfer_patch.json adds PATCH /orders/{id} by copying POST metadata and retaining revision-one captures. Rebuild the matrix from profile GET_POST_PATCH_R2. The custom media type is application/vnd.maknow.order-patch+json; it is neither JSON Patch nor JSON Merge Patch. An omitted quantity preserves the current value; explicit null receives 422; a string or unknown member receives 400. A valid quantity assigns an absolute value, and assigning the existing value is a no-op. Do not copy POST creation or replay semantics.

The changed operation consults a read-only availability service whose data is maintained by a background refresh worker. For a change, probe before the local write. The design budget is 100 ms; an injected timeout yields 503 and no local write, while an unexpected failure yields 500 and no write. Omission and same-value no-ops make no probe. The Python model injects these outcomes; it does not measure or enforce a real 100 ms deadline or run the worker. Real deadline, cancellation and service behavior remain unverified.

Use all 12 added PATCH cases: changed value, omission, null, timeout, missing order, unauthenticated, forbidden, invalid range, wrong media, wrong type, unexpected failure and same value. The full target retains the 19 baseline cases as well. Explain the consequences of each missing or stale observation, identify every document/capture/review that needs renewal, and propose the smallest implementation repair. A correct response must distinguish the current defective fixture from evidence needed after repair. No filled transfer verdict is supplied.

For an optional model rehearsal, copy candidate metadata, implement the target profile, regenerate its OpenAPI and execute the new requests. Do not rewrite expected responses to fit faulty behavior. A real mutating background job would need an acceptance/status, outbox or other explicit consistency contract; the read-only probe here does not settle that design.

NET-002-F3 — Transfer check. Why does the timeout require a new failure-and-effects case? Explain why returning 201 from the copied POST contract cannot establish a partial update. Return to the target profile if your answer reuses the old revision without rebuilding evidence.

Preserve what was actually established

A submission contains fixture and context identity, fixture_sha256, policy_sha256, contracts_sha256, evaluation date, scope, readiness state, typed issues with pointers, rationale, minimal repair and review trigger. Pointer syntax is standard JSON Pointer; use array indexes from the actual file, and escape ~ as ~0 and / as ~1 inside member names. A pointer identifies evidence, not an invented replacement value.

contracts.json supplies requests and expected outcomes. The model produces observations. The fixture preserves selected observations and deliberate mutations. The public checker checks structure and binding; instructor semantic evaluation compares the visible rules and complete cause set. A person must be able to reproduce your explanation without access to hidden reasoning. Do not confuse these four jobs.

Keep the no-write and final-row observations next to authentication, validation, replay and timeout cases. A code labelled PASS without this evidence is insufficient. Also record the configuration and actual host: Python model, real ASP.NET test host and deployed service are different scopes. UNVERIFIED real-framework execution remains visible even when the synthetic exercise is accepted.

AI may organize supplied records, calculate digests and draft questions. It may not invent a test run, credential authority, current capture, permission from an owner or deployment approval. A new implementation, schema, policy, dependency boundary, framework version or expired review triggers a new bound evaluation.

Defend the matrix

NET-002-S1 — Retrieval. Explain the API boundary owned by this lesson, distinguish documentation from enforcement, and name one adjacent non-goal. Identify a state that must stay unresolved without execution evidence.

NET-002-S2 — Application. Build the complete baseline matrix and defend its bounded result. Explain why rejecting an unauthenticated POST is a successful negative test and why that does not prove real credential validation.

NET-002-S3 — Diagnosis. Diagnose the removed POST authorization while its OpenAPI path remains. Identify every invalidated dimension, client/data consequence, minimal repair and required fresh evidence. Explain why changing a hash cannot create a missing run.

NET-002-S4 — Transfer. Recompute transfer_patch from its own evidence. Explain omission versus null, media/schema and success status, the read-only dependency's timeout/failure effects, and all revision-bound observations that must be renewed. Do not copy the baseline result.

All five rubric dimensions must be sufficient: identity/contract, exact evidence binding, negative evidence, bounded decision and transfer. A correct aggregate with incomplete causes fails the relevant dimension; a complete code list without causal explanation also fails. Repair a boundary error with the mental model, response errors with the technical explanation, and copied transfer with a newly built matrix.

Sources and freshness

Ten primary sources were checked on 2026-09-12, with review due 2026-10-18 or earlier after a material framework, schema or security change. The downloadable sources.json and source_links.md preserve their links and claim boundaries. Documentation is pinned to ASP.NET Core 10; do not silently substitute a newer framework's defaults.

FACT denotes documented platform or protocol behavior. INFERENCE is a conclusion supported by supplied observations. DESIGN denotes this exercise's status policy, strict shapes, replay rules, safe-body whitelist, state names and 100 ms budget. The bounded acceptance rule is DESIGN, not a Microsoft or IETF certification. External documentation cannot create a missing execution receipt. Publish reviewed changes as a new version while preserving these inputs, sources and dated observations.