.NET HTTP API

When one class owns one route, a reviewer finds the input mapping, the dispatch, and the result mapping for that route in one place, and no route drifts into a second pattern unnoticed. Without that rule, operations share classes or helpers, and a change to one route silently affects another. This provision binds litespec/backend/api#map-one-operation-per-endpoint for .NET.

The WebApi project owns this contract:

internal interface IEndpoint
{
    void MapEndpoint(IEndpointRouteBuilder endpoints);
}

At startup, the host scans the modules assembly through its one public marker for non-abstract IEndpoint implementations, registers each one once as a singleton, and calls MapEndpoint in type-name order. The scan uses framework reflection and dependency injection, so it needs no extra scanning package.

Reviewed forWhich mapped routes escape one IEndpoint type converting input, dispatching, and mapping the result? Look at the endpoints in the use case folders.

Marked guidance: a reviewer answers this question.

Controllers and endpoint classes route, filter, and map errors through different models. When both exist, a reviewer checks two mappings for every behavior, and error responses drift apart. One model means one place defines how requests reach handlers and how failures reach clients.

Checked bydotnet build reports LS2003 for a WebApi class deriving from ControllerBase or carrying ApiController.

Marked checkable: the tool named here checks it.

Generated clients name their calls from operationId, so an unnamed or unstable operation breaks every client regeneration. Authorization and Problem Details metadata tell a client which policies apply and which failures to handle; without them the client guesses. Route-lambda comments never reach the contract, so the summary and description are declared explicitly. This provision binds litespec/backend/api#declare-stable-operation-metadata-in-the-contract for .NET.

Reviewed forWhich operations miss a stable operationId, authorization, request, success, or Problem Details metadata, typed results or Produces entries, or a summary? Look at each operation.

Marked guidance: a reviewer answers this question.

The specification records each refusal with its stable code and no transport status, so the stack derives the status its transport needs. The handler uses ASP.NET Core AddProblemDetails with one IExceptionHandler: validation failures answer 400, missing targets answer through the operation's 404 policy, forbidden failures answer 403 or the declared 404 disclosure policy, conflicts and state rejections answer 409, and unexpected failures answer 500 with code internal_error. The derived invalid-input refusal answers 400 under the project's refusals.invalidInput code, and the derived forbidden refusal answers 403 or the declared 404 under the project's refusals.forbidden code. Known Domain exception types map individually, and a cancellation from a disconnected request is not reported as an application error. The outcome-to-status assignment lives in litespec/backend/api#use-consistent-status-codes; this provision binds it for .NET.

The handler registers through the framework's Problem Details services:

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

The handler maps each known exception type to its status and code, and answers 500 with code internal_error for the rest.

Reviewed forWhich refusal codes escape the one IExceptionHandler, or map outside their outcome-table status? Look at the WebApi global handler.

Marked guidance: a reviewer answers this question.

A concrete base record cannot mark the discriminator as required, so a client could send a payload that names no case. String discriminators carry the Domain union's stable case codes, so the wire value survives renames of code identifiers. Without the discriminator, deserialization picks a case by shape, and two cases with similar fields become ambiguous. This provision binds litespec/backend/api#mark-polymorphic-models-with-discriminators for .NET.

• Declare an abstract base record carrying JsonPolymorphic and one JsonDerivedType per case.
• Carry the metadata on the type, not only in host options.
• Name the discriminator through TypeDiscriminatorPropertyName, using a name such as type or outcome.
• Opt derived types in explicitly, so an unregistered runtime subtype fails serialization.
• Complete discriminator metadata that the generator omits with a document or schema transformer.

Reviewed forWhich data-bearing sets escape the abstract base record with one sealed record per case and the oneOf string discriminator? Look at each data-bearing set.

Marked guidance: a reviewer answers this question.