HTTP API

One endpoint class per route operation gives each route a single owner, so its input mapping, dispatch, and result mapping live in one place. An endpoint that served several operations would mix their mappings and force one class to change for unrelated routes.

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.

Reviewed forWhich mapped routes resolve outside one endpoint type with one mediator dispatch? Look at the route table beside the use case folders.

Marked guidance: a reviewer answers this question.

An endpoint that took a repository, session, provider, or application service could reach business state or providers without passing the pipeline. Endpoints hold no request-scoped dependency because the application registers them at startup; handlers take mediators and HTTP-boundary services such as an actor accessor.

Reviewed forWhich endpoint constructors take more than mediators and HTTP-boundary services? Look at the endpoint constructors in the use case folders.

Marked guidance: a reviewer answers this question.

One global handler produces every error response from every failure type. An endpoint that caught a failure would create a second mapping for the same failure, and the two would diverge: the same refusal would answer different statuses or codes depending on which endpoint raised it.

Reviewed forWhich endpoint bodies catch a use-case, domain, or validation failure? Look at the endpoint bodies beside the global handler.

Marked guidance: a reviewer answers this question.

Authentication establishes who is calling, not whether the caller is allowed to act on this specific resource. Coarse policies at the endpoint check the caller; the application guard decides the target from the access the use-case record declares. An endpoint that decided target authorization would duplicate business data access the guard already owns. Target authorization lives in litespec/backend/application#enforce-target-authorization-in-the-pipeline.

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

Reviewed forWhich endpoint policies decide target authorization instead of coarse authentication, role, or scope? Look at the endpoint policies beside the application guard.

Marked guidance: a reviewer answers this question.

A stable machine-readable code lets a client branch on the failure without parsing prose, and the trace identifier connects the response to its diagnostics. One entry per field failure tells the caller everything wrong with the request in one answer. RFC 9457 defines the Problem Details media type the contract uses.

The serialized contract is:

{
  "type": "https://example.test/problems/validation",
  "title": "Request validation failed",
  "status": 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 validity findings exist, carrying their member, code, and message. code carries the refusal result's stable 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.

The global handler maps validation failures to 400, missing targets through the operation's disclosure policy, and forbidden failures to 403 or the declared 404. The derived invalid-input refusal answers 400, and the derived forbidden refusal answers 403 or the declared 404. It maps conflicts and state rejections to 409, and unexpected failures to 500 with code internal-error. It maps each known domain failure individually. It does not report cancellation from a disconnected request as an application error.

In the Claimwick product, reimbursing an expense that is not approved ends with result/reimburse-expense.not-approved, which carries the code spending.not-approved and the status 409. For example, the global handler answers:

{
  "type": "https://example.test/problems/conflict",
  "title": "Not approved",
  "status": 409,
  "detail": "The expense is not approved.",
  "instance": "/api/expenses",
  "code": "spending.not-approved",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

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

Reviewed forWhich error responses miss the stable code, the traceId, or one errors entry per field failure? Look at the error responses at the API boundary.

Marked guidance: a reviewer answers this question.

A client branches on status before it reads a body, so a status that disagrees with the outcome table hides the real outcome. The stack derives the status from the use-case result: each success and refusal kind maps to exactly one status, with no recorded status on the record. The outcome table assigns each result its status once, and the operation returns exactly that status.

Reviewed forWhich operation responses return a status outside the outcome table? Look at each response beside the outcome table.

Marked guidance: a reviewer answers this question.

An upload without a declared size or media-type bound lets one caller send work the server never agreed to store or inspect. Declaring both bounds on the use-case record lets the server refuse an oversize file or an undeclared type before storage, and lets a reviewer see the limit beside the use case that owns the file.

The Claimwick submit-expense upload declares the size and the image media types a receipt photo may carry, and the server refuses a larger file or another media type before it stores anything.

Reviewed forWhich upload operations lack a declared size or media-type bound, or accept a file outside either bound? Look at each upload endpoint beside its use-case record.

Marked guidance: a reviewer answers this question.

A claimed media type and a file name are caller input, so either one can name an image while the bytes carry anything else. Reading the type from the content itself keeps the declared media-type bound honest, because the check runs on what the server stores rather than on what the caller says it sent.

A Claimwick receipt photo named as an image is stored as an image only when its bytes read as one of the declared image types, and bytes of another type are refused even when the name and claimed type agree.

Reviewed forWhich upload operations trust a claimed media type or file name over the file bytes? Look at the type check of each upload endpoint beside the declared media types.

Marked guidance: a reviewer answers this question.

Storing a file is provider work, like storing an aggregate, so the endpoint stays a transport adapter and the handler stays on behavior. Infrastructure owns the storage provider, its configuration, and its errors, so a project can change where files live without touching an endpoint or a handler.

The Claimwick endpoint for a receipt photo converts the request to its command and dispatches it, the handler stages the expense, and Infrastructure writes the photo bytes to the configured store.

Reviewed forWhich endpoints or handlers write file bytes to a storage provider directly? Look at the upload endpoints and handlers beside the Infrastructure storage code.

Marked guidance: a reviewer answers this question.

A stored file carries the data of the record it belongs to, so a direct storage address would serve that data to anyone holding the address and skip the owning use case's grant and tenant scope. Routing each download through its owning use case keeps one authorization decision for the file and for the record it belongs to.

A Claimwick receipt photo downloads through the use case that owns the expense, so only an actor its access allows reads the photo, and no storage address serves it on its own.

Reviewed forWhich stored files are reachable outside a download use case and its declared access? Look at the download endpoints and the storage addresses beside each owning use case.

Marked guidance: a reviewer answers this question.

Cookies travel with every request, including ones a malicious page triggers, so a cookie-authenticated write needs proof the project's own page sent it. A page on another site adds no custom header, so the header's absence exposes a cross-site forgery. A write is any request other than GET, HEAD, or OPTIONS. The header takes the form X-<Project>-Request: 1, with the exact name set in project configuration.

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.

Reviewed forWhich cookie-authenticated writes without the marker header escape the 401 answer? Look at the write requests with cookie authentication.

Marked guidance: a reviewer answers this question.

A predictable route shape lets a caller derive an unfamiliar operation from a familiar one: plural resource segments, kebab-case subresources, route parameters for identity, query parameters for filtering, and command data in the body. A route that encoded actions or identities anywhere else would force the caller to read each route's documentation. For a transition beyond the five verbs, AIP-136 defines the custom-method form.

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

Reviewed forWhich routes break the plural segments, kebab-case subresources, identity parameters, filter queries, or body command data? Look at the route table entries.

Marked guidance: a reviewer answers this question.

A partial update names only the fields it changes. Sending them with PATCH and the merge-patch media type gives those semantics a standard meaning; a PUT body for a partial change either repeats fields the caller does not change or invents merge semantics per field. RFC 5789 defines PATCH and RFC 7386 defines the merge-patch media type.

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 (RFC 9110 section 9.3.4), and DELETE stays a hard-state transition.

Reviewed forWhich partial updates arrive outside PATCH with the merge-patch media type? Look at the partial update requests.

Marked guidance: a reviewer answers this question.

An unbounded collection read turns one caller into a source of unbounded database and serialization work. Deterministic ordering keeps pages stable, the declared default limit bounds the common case, and the declared maximum of 100 or lower caps the worst case. The use-case record declares its paging with order, cursor or offset, default limit, and maximum limit, and the endpoint applies exactly that. Cursor mechanics live in litespec/backend/api#use-opaque-cursors-for-collection-paging and litespec/backend/api#version-cursors-with-stable-sort-values.

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
  }
}

Reviewed forWhich collection responses lack deterministic order, or exceed the declared default or maximum limit? Look at the collection responses beside their records.

Marked guidance: a reviewer answers this question.

A cursor that exposed offsets or internals lets callers craft requests against storage details and breaks when those details change. An opaque cursor keeps paging state server-defined, and the endpoint treats it as untrusted input: a malformed cursor, or an unsupported cursor version, answers 400 with code invalid-cursor.

Reviewed forWhich malformed cursors escape the 400 answer with code invalid-cursor? Look at the collection endpoints.

Marked guidance: a reviewer answers this question.

Paging walks a sorted sequence, so the cursor names exactly where the last page stopped: the version lets the sort evolve without breaking stored cursors, and the last stable sort values with a unique tie-breaker keep the walk exact when values repeat. The tie-breaker matches the query's stable order under litespec/backend/api#bound-collection-queries. No sensitive value travels in readable form, because callers store and replay cursors.

Reviewed forWhich cursor payloads miss a version, the last sort values, or a unique tie-breaker, or leak a readable secret? Look at the cursor payloads.

Marked guidance: a reviewer answers this question.

A handwritten contract drifts from the code it describes with the first unmirrored change. Generating the document during the Release build keeps the contract a function of the code, so the file the pinned generator reads stays current.

The API source artifact is apps/api/openapi/{ProjectName}.json.

Build-time generation boots the host. A boot reaches every startup guard. A project whose composition refuses to start without a secret, a certificate, or a reachable dependency generates no 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 a typed consumer reads 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.

Reviewed forWhich Release builds skip regenerating the OpenAPI artifact, or which contract gates pass on a changed tree? Look at the Release build output and the contract gate.

Marked guidance: a reviewer answers this question.

Generated clients name their methods from operationId, so an unstable name renames client code on every generation. Authorization metadata cites the enforced policies and Problem Details metadata covers every documented failure status, so the client models security and failure before its first call. Comments on handlers are not contract documentation, so operations carry explicit summaries and descriptions.

Reviewed forWhich operations in the generated contract miss operationId, authorization, request, success, failure, or summary entries? Look at the operations in the generated contract.

Marked guidance: a reviewer answers this question.

The operationId names an operation for client code and keeps its casing for method names, so it is not the record identifier. Carrying the identifier itself in an extension, which the OpenAPI specification reserves for this kind of metadata, lets an integrator, a gateway log, or a support person go from an operation straight to its specification page. The value comes from the generated map of operation names to use cases, so it is written once, in the endpoint's mark.

The Claimwick operation SubmitExpense carries "x-litespec-use-case": "use-case/spending.submit-expense".

Checked bylitespec model check reports operation-use-case-drift (level S) for an operation in the committed contract whose x-litespec-use-case is missing or differs from the use case its endpoint's mark names.

Marked checkable: the tool named here checks it.

A committed artifact makes every contract change visible in review and lets CI fail when the document was not regenerated. Without the committed file, a breaking contract change hides inside a code change. Consumers read the artifact through the generated client, model, schema, and query-option packages.

Reviewed forWhich frontends or external consumers read an uncommitted or stale OpenAPI artifact? Look at the committed artifact beside its consumers.

Marked guidance: a reviewer answers this question.

A consumer that learns an authentication requirement from a runtime 401 has already built the wrong client: declared security schemes and per-operation requirements let it build the right one. Handwritten security metadata drifts from registered schemes, so the document derives them from the registered authentication schemes.

The implementation reads the registered authentication schemes and adds the matching securitySchemes and security entries. Handwritten security metadata drifts from registered schemes. An operation whose access grant is anonymous declares no security requirement.

Reviewed forWhich authenticated operations miss their security schemes and requirements in the generated contract? Look at the operations in the generated contract.

Marked guidance: a reviewer answers this question.

A caller that learns limits from the document validates before sending; a caller that learns them from runtime rejections discovers one limit per failed request. Declaring the closed value set, bounds, format, and required control headers of each field and parameter moves every checkable limit into the contract.

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. A converter on the boundary type keeps every serializer on 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.

Reviewed forWhich contract schemas miss value sets, bounds, formats, or required control headers for a field? Look at the schemas in the generated contract.

Marked guidance: a reviewer answers this question.

Development tooling exposes the full API surface for exploration, which is what development needs and what a hosted environment leaves unoffered. Mapping it in Development only keeps exploration local while hosted environments serve only the API.

Reviewed forWhich hosted environments serve exploration tooling, or which Development hosts hide it? Look at the mapped endpoints in each environment.

Marked guidance: a reviewer answers this question.

Each case of a closed set carries different data, and a transport shape that differs from its Domain set discards information the Domain carries. Preserving the shape keeps every case and its data on the wire. 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.

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.

Reviewed forWhich transport models drop a case or its data from their Domain set? Look at each transport model beside its Domain set.

Marked guidance: a reviewer answers this question.

A label-only set carries no case data, so its labels are the complete contract and a string enum carries them exactly. The permission to use a plain enum for this one situation lives in litespec/backend/domain#model-every-closed-set-of-domain-values-as-a-closed-type-hierarchy.

Reviewed forWhich label-only sets escape the string enum in the contract? Look at the label-only sets in the contract.

Marked guidance: a reviewer answers this question.

A polymorphic payload without a discriminator forces the reader to guess the case from its fields. A required string discriminator names the case on every payload, so no payload validates without one. The strings equal the Domain union's stable case codes and stay stable across identifier renames.

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

Reviewed forWhich data-bearing sets escape the oneOf model with a required string discriminator? Look at the data-bearing sets in the contract.

Marked guidance: a reviewer answers this question.

Collapsing a data-bearing set into an enum discards the data that distinguishes its cases, and reusing a Domain or Application type as the wire contract couples the public contract to inner shapes. Each layer owns its own contract type per litespec/backend/architecture#own-each-layers-contract-types, so the wire contract is always a dedicated transport model. Narrowing follows litespec/backend/application#record-a-decision-for-closed-set-narrowing.

Reviewed forWhich wire contracts collapse a data-bearing set into an enum or reuse a Domain or Application type? Look at each wire contract.

Marked guidance: a reviewer answers this question.

A use case that reads one way in its record, another in its message type, and a third in its audit action forces every trace across layers through a translation table only the author holds. The record id is the name; the message type, the endpoint operation id, and the audit action repeat it in their own casing, so a reader follows one name from the page to the wire to the audit log.

use-case/spending.reimburse-expense travels as ReimburseExpenseCommand, operation id ReimburseExpense, and audit action reimburse-expense; an operation id of PayExpense is reported.

Reviewed forWhich message types, operation ids, or audit actions carry a different name than their use case? Look at each use case's message type, operation id, and audit action.

Marked guidance: a reviewer answers this question.