HTTP API

Requirement An endpoint MUST 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.

Example At startup, the application discovers endpoint implementations, registers each one once, and maps them in deterministic name order. Discovery uses the platform's own reflection and dependency injection. It needs no separate scanning package.

Requirement An endpoint MUST NOT take an aggregate repository, a persistence session or context, a provider client, or an application service.

Rationale The application registers endpoints at startup, so they hold no request-scoped dependency. Endpoint handlers take mediators and HTTP-boundary services such as an actor accessor.

Requirement An endpoint MUST NOT catch a UseCaseException, a DomainException, or a validation failure.

Rationale One global handler produces every error response, so a caught exception at the endpoint creates a second, divergent mapping.

Requirement A WebApi endpoint MUST enforce only coarse authenticated, role, or scope policies, leaving target decisions to the application guard.

Rationale Authentication establishes who is calling. It does not establish that the caller may act on this specific resource. Target authorization lives in litespec/backend/application#enforce-target-authorization-in-the-pipeline, which decides from the permissions the use case needs.

An operation applies a stable forbidden or not-found policy when revealing that a resource exists would leak information.

Requirement An error response MUST use RFC 9457 Problem Details carrying a stable application code, the current traceId, and an errors entry for each field failure.

Rationale A stable machine-readable code lets a client branch on the failure, and the trace identifier connects the response to its diagnostics. RFC 9457 obsoletes RFC 7807 and defines the media type. The contract cites the document a client implementer reads.

Example The serialized contract is:

{
  "type": "https://example.test/problems/validation",
  "title": "Request validation failed",
  "httpStatus": 400,
  "detail": "One or more values are invalid.",
  "instance": "/api/posts",
  "code": "validation_failed",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": [
    {
      "field": "title",
      "code": "required",
      "message": "Title is required."
    }
  ]
}

type is a stable absolute URI owned by the consumer. errors appears only when ValidationFailure entries exist, carrying their member, code, and message. code carries the refusal Result's failure code, and detail carries the free-form prose explanation. A request body names the same pair code and reason under litespec/backend/api#name-failure-pairs-code-and-reason.

WebApi maps Application member names to their public JSON field names. traceId carries the trace identifier from the current W3C Trace Context traceparent, with the request identifier as fallback. The same shape applies to authentication and authorization failures.

In the dotnet stack, the example uses ASP.NET Core AddProblemDetails and one IExceptionHandler. It maps validation exceptions to 400, missing targets through the operation's 404 policy, and forbidden failures to 403 or the declared 404 disclosure policy. It maps conflicts and state rejections to 409, and unexpected exceptions to 500 with code internal_error. It maps known Domain exception types individually. It does not report cancellation from a disconnected request as an application error.

In the library circulation product, borrowing an unavailable copy ends with result/borrow-copy.copy-unavailable, which carries the code failure/lending.copy_not_available and the status 409. For example, the global handler answers:

{
  "type": "https://example.test/problems/conflict",
  "title": "Copy unavailable",
  "httpStatus": 409,
  "detail": "The copy is unavailable.",
  "instance": "/api/loans",
  "code": "failure/lending.copy_not_available",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

The endpoint never catches the failure. The diagram shows how a Domain exception or a validation failure reaches the global handler and becomes a status with a Problem Details body.

Requirement A result MUST carry httpStatus exactly when an HTTP entry point reaches its use case.

Rationale The outcome table, the route, and the tests read one recorded status. A use case reached only by reactions or jobs has no HTTP answer to record.

Requirement A WebApi operation MUST return the status code that its outcome table assigns.

Rationale A client branches on status before it reads a body, so an inconsistent code hides the outcome.

Example

Requirement The API MUST refuse a cookie-authenticated write without the project's marker header.

Rationale A write is any request other than GET, HEAD, or OPTIONS. The header takes the form X-<Project>-Request: 1. You set the exact name in project configuration. A page on another site cannot add the header, so its absence exposes a cross-site forgery.

The refused request is unauthenticated, so it answers 401 under litespec/backend/api#use-consistent-status-codes. The frontend pages own sending the header. This rule owns the API refusal.

Requirement A route MUST use lowercase plural resource segments, kebab-case subresources, route parameters for identity, query parameters for filtering, and the body for command data.

Rationale A predictable route shape lets a caller derive an unfamiliar operation from a familiar one.

Example A route carries the authenticated actor identifier only when that actor is intentionally addressing another actor as a resource.

Requirement A WebApi route MUST express a state transition the five HTTP verbs cannot carry as a POST custom method ending in a colon-suffixed verb.

Rationale AIP-136 defines the custom-method form for actions outside the five standard methods. A path segment names a resource. A state-noun segment such as /closure and a bare verb segment such as /abandon both encode the action, so neither predicts the other. The colon marks the final segment as a command rather than a nested resource.

Example

POST /api/shipments/{shipmentId}:cancel
POST /api/merchants/{merchantId}:close
POST /api/orders/{orderId}/refund-requests/{refundId}:decide

The operationId keeps its verb-noun form, so CancelShipment names the same transition the path states.

Requirement A WebApi operation MUST apply a partial update with PATCH and the application/merge-patch+json media type.

Rationale RFC 5789 defines PATCH and RFC 7386 defines the merge-patch media type. A PUT body for a partial change either repeats fields the caller does not change or invents merge semantics per field.

Example A partial update sends only the changed members with Content-Type: application/merge-patch+json, and the endpoint reads the body as a sparse patch. A PUT keeps replacing the whole resource, and DELETE stays a hard-state transition.

Requirement A PUT operation MUST replace the whole resource or sub-resource its path names.

Rationale A PUT body that carries a subset forces the server to choose between dropping omitted members and inventing per-field merges. The partial path is PATCH under litespec/backend/api#apply-patch-to-a-partial-update.

Example A whole replacement sends every editable member, and an omitted member removes its value rather than keeping the stored one.

Requirement A collection endpoint MUST apply deterministic ordering, a default limit of 20, and the use case's declared maximum limit of 100 or lower.

Rationale An unbounded collection read turns one caller into a source of unbounded database and serialization work. Query-side ordering lives in litespec/backend/api#bound-collection-queries, which this rule's ordering follows. Cursor mechanics live in litespec/backend/api#use-opaque-cursors-for-collection-paging and litespec/backend/api#version-cursors-with-stable-sort-values.

Example A request uses after as an opaque cursor and limit as a positive integer. The implementation fetches one record beyond the requested limit to determine whether another page exists. The response uses one shape:

{
  "items": [],
  "page": {
    "limit": 20,
    "nextCursor": null,
    "hasMore": false
  }
}

Requirement A collection endpoint MUST page with an opaque cursor and refuse a malformed cursor with 400 and code invalid_cursor.

Rationale The endpoint treats the cursor as untrusted input. An unsupported cursor version answers the same refusal.

Requirement A paging cursor MUST carry a version and the last stable sort values, including a unique tie-breaker, and no sensitive value in readable form.

Rationale The version lets the sort evolve without breaking stored cursors. The tie-breaker matches the query's stable order under litespec/backend/api#bound-collection-queries.

Requirement A WebApi project MUST generate its OpenAPI document during the Release build.

Rationale A handwritten contract drifts from the code it describes.

Example The API source artifact is apps/api/openapi/{ProjectName}.json. In the dotnet stack, WebApi references Microsoft.AspNetCore.OpenApi and Microsoft.Extensions.ApiDescription.Server, enables OpenApiGenerateDocuments, sets OpenApiDocumentsDirectory to that directory, and passes --file-name {ProjectName} through OpenApiGenerateDocumentsOptions.

Build-time generation boots the host. In the dotnet stack, Microsoft's own guidance boots the host the same way. A boot reaches every startup guard. A project whose composition refuses to start without a secret, a certificate, or a reachable dependency cannot generate its contract from a clean checkout. Two answers are valid, and the project records which one it uses under litespec/backend/api#generate-the-contract-without-hosted-dependencies.

Generation without hosted dependencies follows litespec/backend/api#generate-the-contract-without-hosted-dependencies.

When TypeScript consumes the API, the pinned generator reads the source artifact. The generated client, its model types, its request schemas, and its query options are one workspace package, because every frontend and every command reads them.

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

Rationale A stable name becomes operationId. Authorization metadata cites the enforced policies, and Problem Details metadata covers every documented failure status. Comments on handlers are not contract documentation, so operations carry explicit summaries and descriptions.

Requirement A WebApi project MUST commit its generated OpenAPI artifact when a frontend or external consumer reads it.

Rationale A committed artifact makes every contract change visible in review and lets CI fail on an unregenerated document. Consumers read the artifact through the generated client, model, schema, and query-option packages.

Requirement A generated OpenAPI document MUST declare the security scheme and per-operation security requirement for every endpoint that enforces authentication.

Rationale A consumer that learns an authentication requirement from a runtime 401 has already built the wrong client.

Example In the dotnet stack, the implementation registers a document transformer that reads registered authentication schemes through IAuthenticationSchemeProvider and adds the matching securitySchemes and security entries. Handwritten security metadata drifts from registered schemes. An intentionally anonymous operation declares no security requirement.

Requirement A generated schema MUST declare the closed value set, bounds, format, and required control headers of each field and parameter it describes.

Rationale A caller learns an operation's limits from the document instead of discovering them through a runtime rejection.

Example A label-only set publishes its values as an OpenAPI enum. A data-bearing set publishes a polymorphic oneOf model with a discriminator per litespec/backend/api#mirror-a-domain-closed-set-as-a-transport-model-of-the-same-shape. In the dotnet stack, a named boundary enum carries [JsonConverter(typeof(JsonStringEnumConverter<T>))] on its type. Every serializer then honors the contract, including a test client using default options. Host-only conversion breaks readers that do not share host configuration.

An operation requiring a control header declares it as a required parameter, for example Idempotency-Key or If-Match. The implementation prefers results, enums, and parameter metadata derived from code over handwritten schemas that drift from code. In the dotnet stack, the implementation uses typed results, typed boundary enums, and parameter metadata.

Requirement A WebApi project MUST expose Scalar and development tooling in Development only.

Rationale Hosted environments do not expose development tooling by default.

Requirement A WebApi transport model for a Domain closed set MUST preserve the shape of that set.

Rationale A transport shape that differs from its Domain set discards information the Domain carries. Label-only sets follow litespec/backend/api#publish-label-only-sets-as-string-enums, and data-bearing sets follow litespec/backend/api#mark-polymorphic-models-with-discriminators. Narrowing follows litespec/backend/application#record-a-decision-for-closed-set-narrowing.

Example A label-only set maps to a string enum. A data-bearing set maps to a polymorphic model with one case per variant, published as oneOf with a discriminator. In the dotnet stack, that model is an abstract base record with one sealed record per case.

Requirement A transport model for a label-only set MUST publish its values as an OpenAPI string enum.

Rationale The permission to use a plain enum for a label-only set lives in litespec/backend/domain#model-every-closed-set-of-domain-values-as-a-closed-type-hierarchy.

Requirement A data-bearing set MUST map to a polymorphic model with one case per variant, published as oneOf with a string discriminator.

Rationale The discriminator property is required on every payload, so no payload validates without naming its case. String discriminators equal the Domain union's stable case codes. Discriminator strings stay stable across identifier renames.

Example

• Declare one polymorphic base with one registered case per variant.
• Carry the metadata on the type, not only in host options.
• Name the discriminator property, using a name such as type or outcome.
• Opt cases in explicitly, so an unregistered subtype fails serialization.
• A document or schema transformer completes discriminator metadata that the generator omits.

Requirement A WebApi transport model MUST NOT collapse a data-bearing set into an enum or reuse a Domain or Application type as the wire contract.

Rationale Each layer owns its own contract type per litespec/backend/architecture#own-each-layers-contract-types. Narrowing follows litespec/backend/application#record-a-decision-for-closed-set-narrowing.