.NET HTTP API

Requirement A WebApi endpoint MUST implement IEndpoint, map one route operation, convert input to an Application message, dispatch through its mediator, and map the result.

Rationale One class per operation gives each route a single owner and keeps the transport boundary reviewable. This provision realizes litespec/backend/api#map-one-operation-per-endpoint in the dotnet stack.

Example The WebApi project owns this contract:

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

At startup, WebApi discovers non-abstract IEndpoint implementations in its assembly. It registers each implementation once as an IEndpoint singleton. It calls MapEndpoint in deterministic type-name order. The discovery code uses framework reflection and dependency injection. It does not require another scanning package.

Requirement A WebApi project MUST NOT route requests through MVC controllers or ControllerBase.

Rationale A second transport pattern splits routing, filters, and error mapping across two models that behave differently.

Requirement An operation MUST declare a stable operationId, its authorization, request, success, and Problem Details metadata, and typed results or Produces metadata, and a summary.

Rationale A stable name through WithName becomes operationId. Authorization metadata cites the enforced policies, and Problem Details metadata covers every documented failure status. Comments on route lambdas are not contract documentation, so operations carry explicit summaries and descriptions. This provision realizes litespec/backend/api#declare-stable-operation-metadata-in-the-contract in the dotnet stack.

Requirement A data-bearing set MUST map to an abstract base record with one sealed record per case, published as oneOf with a string discriminator.

Rationale A concrete base cannot mark the discriminator property as required, so the base stays abstract. String discriminators equal the Domain union's stable case codes. Discriminator strings stay stable across identifier renames. This provision realizes litespec/backend/api#mark-polymorphic-models-with-discriminators in the dotnet stack.

Example

• 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.