timewarpengineering/timewarp-architecture/tw-web-api-contracts

Web API Contracts

Endpoint-centric, JSON-over-HTTP contracts designed for Blazor front ends. Each endpoint owns its request/response types. Mutability signals purpose: immutable members are read-only display data; mutable members on I*Details interfaces bind in EditForm without a separate view model. Shared validation lives on interfaces and is composed into per-endpoint validators.

This pattern appears across TimeWarp-based solutions. Project names vary (web-contracts, Web.Contracts, Api.Contracts, …) but the contract shape is the same.

Why endpoint-centric, not entity-centric: each operation owns its request/response types so endpoints do not couple through a shared entity DTO (over-fetch, under-fetch, and cross-endpoint breakage). Share structure and validation through I*Details interfaces composed into per-endpoint validators — that is what lets Blazor bind EditForm to one shape without a parallel view model.

Why generate FastEndpoints on both hosts: route, verb, and auth live on the contract, so there are no hand-written MVC BaseEndpoint shims. Validation stays on the mediator's FluentValidationBehavior. Hosts set EnableApiEndpointGeneration plus an ApiEndpointContractAssemblies AssemblyName allow-list (TWE008).

Browser-protocol endpoints (the exception)

A hand-written EndpointWithoutRequest at features/<slice>/…-endpoint-server.cs is allowed when the HTTP response is not the contract's JSON: an auth challenge, a form POST answered with a redirect, or an antiforgery token fetch. The living cases are ChallengeEntraEndpoint, SignOutBrowserSessionEndpoint, and SignOutAntiforgeryTokenEndpoint.

• The path lives on a shared contracts class.
• Any session or state change dispatches the existing mediator handler. Do not write a second

implementation.

• The Design region says why the generator does not fit.
• These bodies share nothing but the route and AllowAnonymous, so a generator is not worth it.
• Validation stays on FluentValidationBehavior. Do not adopt FastEndpoints' validator integration.

Ordinary JSON operations stay generated. The filename function endpoint is for this exception (tw-feature-placement).

Detection — find the pattern in the current repo

Activate when any signal matches:

The mediator is TimeWarp.Mediator (not MediatR). IQuery<T>, ICommand<T>, and IIdempotentCommand<T> all extend IRequest<T>, so handlers stay IRequestHandler<TRequest, TResponse>.

Before adding a contract, read 2–3 existing contracts in the same repo to match namespace root, folder casing, test project layout, and mock-service registration.

Folder and namespace rules

Casing: kebab-case paths are canonical; if the repo already uses PascalCase folders (Features/Admin/Roles/), match it. Never mix casings within one repo.

The contract attributes (source-generated)

Two layers of attributes. Route/request attributes are emitted as public types in TimeWarp.Foundation.Features by the bundled contracts generator (class must be `partial`). Server-generation attributes live in TimeWarp.Architecture.Attributes and mark which contracts become hosted FastEndpoints.

Route / request attributes (on nested Query/Command)

The FastEndpoint generator matches TimeWarp.Foundation.Features.ApiRouteAttribute by fully qualified metadata name; the contracts generator emits that public type, so it ignores the generated app's RootNamespace.

[ApiRoute] parameter constraint grammar

Tokens are {Name} or {Name:constraint}; a type starts only after a colon, so bare {Date}/{LocationId} stay full identifiers typed string. guid → Guid, datetime → DateTime, min(n)/max(n) → int, other tokens as written. Full constraint table and unsupported forms: route-grammar.md.

FastEndpoint generation (on the outer operation class)

Both web-server and api-server host endpoints generated from contracts — there are no hand-written MVC BaseEndpoint shims in the template. Opt in per operation:

Picking anonymous when the contract shouldn't be is caught too: TWA0014 flags a contract that carries both markers, or [EndpointAllowAnonymous] alongside a nested Query/Command that declares IAuthApiRequest (manually or via [AuthApiRequest]) — see the auth-forms section below for why that combination is a contradiction, not just a style nit.

[ApiEndpoint]
[EndpointAuthorize
(
  Policy = PermissionIds.IdentityRead,
  AuthenticationSchemes = AuthenticationSchemeNames.AgentToken
)]
public static partial class GetAgentIdentity
{
  [ApiRoute("api/identity/agent/me", HttpVerb.Get)]
  public sealed partial class Query : IApiRequest, IQuery<OneOf<Response, SharedProblemDetails>>;
  // …
}

Policy names (TWA0024): [EndpointAuthorize] Policy must equal a policy the hosting server registers (web: PermissionIds.*; named policies via AddPolicy). Prefer a contracts-visible const over a literal.

Scheme lists: hosted [EndpointAuthorize] must set AuthenticationSchemes (AuthenticationSchemeNames on web); permission policies carry no scheme list, so omitting it authenticates only the host default scheme. Details and per-surface table: endpoint-auth.md.

Validation stays on the mediator (FluentValidationBehavior). Do not re-validate in handlers and do not wire FastEndpoints' own FluentValidation integration (IncludeAbstractValidators = false). Handlers implement business logic only; the generated endpoint is pure HTTP plumbing.

Server projects set <EnableApiEndpointGeneration>true</EnableApiEndpointGeneration> and must set ApiEndpointContractAssemblies to the hosted contracts AssemblyName (web-contracts on web-server, api-contracts on api-server — not the namespace). Empty, mistyped, or unmarked names are TWE008. Hosted contracts assemblies apply [assembly: ApiEndpointsEmbedded]; host generators walk only marked refs.

HTTP verbs

The verb is the contract's [ApiRoute] verb. Generated FastEndpoints take it from there. Do not hand-write a second verb. Analyzer id TWA0005 (MVC verb vs [ApiRoute]) is retired and reserved.

The kind does not pick the verb, and the verb does not pick the kind. The column above is the usual pairing, not a rule: IIdempotentCommand promises that a retry is safe, so use ICommand when the handler cannot keep that promise. See neutral-operations.md.

Neutral operations: one contract, three bindings

The TimeWarp.Contracts package adds the transport-neutral part of a contract. Its version pin is its own line in Directory.Packages.props. The same request class is an HTTP endpoint, a CLI command, and an MCP tool:

• Name, group, and title: [Operation("roles.get", Description = "…", Group = "…", Title = "…")]

on the nested Query/Command. A blank title means no title. [Destructive] and [OpenWorld] are tri-state: omitted is unset, not false. MCP treats an omitted destructive hint as true and reads it only when the tool is not read-only. Generators copy the hints only when [Operation] has a non-blank name. Kind still supplies read-only and idempotent.

• Kind: the mediator interface (IQuery<T>, ICommand<T>, IIdempotentCommand<T>). It is

never an attribute argument.

• Bindings: HTTP comes from [ApiRoute] + [ApiEndpoint] (this template). CLI and MCP come

from TimeWarp.Nuru, which reads the same contract and dispatches through the mediator.

TWA0035 (info) suggests [Operation] on a hosted contract that lacks one. Members, kind choice, bindings, and the catalog: neutral-operations.md.

Contract shell

Every operation is a public static partial class named for the operation: