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: both web-server and api-server host endpoints generated from contracts. Route, verb, and auth live on the contract ([ApiRoute], [ApiEndpoint], exactly one of [EndpointAuthorize] / [EndpointAllowAnonymous(reason)]). There are no hand-written MVC BaseEndpoint shims. Validation stays on the mediator's FluentValidationBehavior; do not wire FastEndpoints' own validator integration. Hosts set EnableApiEndpointGeneration and an ApiEndpointContractAssemblies AssemblyName allow-list (web-contracts, api-contracts) so transitively referenced contract assemblies do not emit foreign endpoints (TWE008).

Detection — find the pattern in the current repo

Activate when any signal matches:

The mediator is TimeWarp.Mediator (not MediatR) — same IRequest<T> shape, different package.

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 via post-initialization output, so it does not follow the generated app's RootNamespace (task 115 sourceName rewrite leaves TimeWarp.Foundation.* intact; contracts already global using TimeWarp.Foundation.Features).

[ApiRoute] parameter constraint grammar

Tokens are {Name} or {Name:constraint}. A type/constraint starts only after a colon — bare names such as {Date}, {LocationId}, {ClientId}, {StaffId}, and {UserId} keep the full identifier and default to string (task 053-003). {Name:string} remains valid.

Constraint arguments are the parenthesized-digits form only ({RoleId:min(1)}). Multiple constraints, comma-separated args, catch-alls, and {name=default} are not parsed. :string is stripped from the emitted RouteTemplate; other tokens are kept ({RoleId:guid}).

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, IRequest<OneOf<Response, SharedProblemDetails>>;
  // …
}

Policy names (task 111 / TWA0024): [EndpointAuthorize] Policy must equal a policy the hosting server actually registers. Web product policies are PermissionIds.* const references (registered by AddPermissionPolicies; policy name == permission id). Named non-permission policies (api-server AgentTokenDefaults.IdentityReadPolicy, web IdentitySessionDefaults.AuthenticatedPolicy) are constant-evaluated AddPolicy first arguments. Contracts cannot reference server-layer constants, so agreement is a server-build check — a drifted literal 403s at runtime; TWA0024 flags it at compile time. Prefer a contracts-visible const (PermissionIds, or a family-local const the server AddPolicy also uses) over a comment-coordinated string literal.

Scheme lists (task 161): hosted [EndpointAuthorize] must set AuthenticationSchemes using AuthenticationSchemeNames (web) or the matching server scheme string (api). PermissionIds policies registered via AddPermissionPolicies have no AddAuthenticationSchemes; ASP.NET Core 10's PolicyEvaluator then authenticates only the host default scheme (identity-session on web). agent-token and mock-identity-session never run unless the generated FastEndpoint emits AuthSchemes(...). Named-policy scheme lists still Combine when present (api-server agent-scope policies) — still declare them on the contract so a policy-registration change cannot drop them. Do not put scheme lists back on permission policies (see IPermissionEvaluator Design region in source/container-apps/web/platform/authorization/i-permission-evaluator-application.cs).

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 must match the server endpoint.

Contract shell

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

public static partial class CreateRole
{
  [ApiRoute("api/Roles", HttpVerb.Post)]
  public sealed partial class Command
    : IAuthApiRequest, IRoleDetails, IRequest<OneOf<Response, SharedProblemDetails>>
  {
    public Guid UserId { get; set; }
    public string Name { get; set; } = null!;
    public string Description { get; set; } = null!;
  }

  public sealed class Validator : AbstractValidator<Command>
  {
    public Validator()
    {
      RuleFor(x => x).SetValidator(new RoleDetailsValidator());
      RuleFor(x => x).SetValidator(new AuthApiRequestValidator());
    }
  }

  public sealed class Response
  {
    public Guid RoleId { get; }
    public Response(Guid roleId) => RoleId = Guard.Against.NullOrEmpty(roleId);
  }
}

Nested types

Return type is always IRequest<OneOf<Response, SharedProblemDetails>> unless returning a stream/file (OneOf<Stream, SharedProblemDetails>).

When the request body may be empty

An empty body (;) is valid only for a route-only request: [ApiRoute] generates the route properties, and nothing else is needed.

If the request implements I*Details (or any data interface), you must declare the interface properties on the class — interface members are not generated, and an empty body will not compile. Do re-declare data properties; do not re-declare route properties (those come from [ApiRoute]).

Auth requests vs. server auth — two different concerns

Canonical statement (task 110): IAuthApiRequest is a client/mock-mode identity signal only — it does not secure the server. [EndpointAuthorize] is the sole marker that secures a generated endpoint. The two are independent axes; TWA0014 enforces that they don't contradict each other.

The three valid states (plus the one that's forbidden)

IAuthApiRequest is detected by either shape the contracts generator produces — the interface implementation or the [AuthApiRequest] attribute itself — so the forbidden row is caught regardless of which of the two forms below produced it.

The two forms of IAuthApiRequest itself

The contract can carry the current user's identity (Guid UserId) so that mock mode — where no server exists to derive identity — can tailor responses per user. Two forms:

Both pair with RuleFor(x => x).SetValidator(new AuthApiRequestValidator()).

Security rule: the server must never trust a client-sent UserId — it re-derives identity from the auth token. The contract field exists for mock-mode tailoring and client-side context; it plays no role in whether the generated endpoint actually requires authentication.

Valid alternative: derive the user entirely server-side (claims/token) and keep contracts auth-agnostic. Choose it when mock-mode identity isn't needed; it is not wrong.

Workflow

1. Identify the operation

Read → get-*/get-*-contracts.cs · Write → create-*|update-*|delete-*/…-contracts.cs (one use-case folder per operation, not a commands/queries split)

2. Scaffold the partial class

• [ApiEndpoint] on the outer operation class when a server host should generate the FastEndpoint
• Exactly one of [EndpointAuthorize(Policy=…, AuthenticationSchemes=…)] (protected; always declare schemes — task 161) or [EndpointAllowAnonymous(reason)] (genuinely public) — required on every [ApiEndpoint] contract; TWA0013 flags the omission, TWA0014 flags picking both, or anonymous alongside IAuthApiRequest
• [ApiRoute("api/...", HttpVerb.*)] on nested Query/Command
• Implement IApiRequest (or IAuthApiRequest — see auth forms above; add IQueryStringRouteProvider when query-string filters apply)
• IRequest<OneOf<Response, SharedProblemDetails>>

3. Bindable data — interface-driven validation

When Blazor will bind and edit the payload:

1. Define I<Feature>Details in a feature-level file (e.g. role-details-contracts.cs).
2. Mutable bindable properties use { get; set; } on the interface (no initializers — interfaces cannot have them; = null! goes on the implementing class).
3. Identity/read-only keys on implementations use { get; init; } or { get; }.
4. Add AbstractValidator<I<Feature>Details> in the same file.
5. Create* / Update* Command implements the interface (and declares its properties).
6. Get* Response implements the interface when the form loads existing data for edit.
7. Endpoint Validator composes: RuleFor(x => x).SetValidator(new RoleDetailsValidator());

This is the core value over default .NET DTO patterns: one shape, shared rules, no parallel view model.

The Blazor side is validation-library-dependent. Binding EditForm to the interface and running the shared validator requires a library that accepts an explicit validator instance — Blazilla: <FluentValidator Validator="@(new RoleDetailsValidator())" />. Libraries that resolve validators by the model's runtime type (Morris.Blazor.FluentValidation) can never find an AbstractValidator<I*Details> for a Command model; Blazored.FluentValidation worked but is deprecated. Living reference: RoleForm.razor (web-spa/features/admin/roles/components/).

See mutability.md.

4. Apply nullability — type declares intent

Nullability is not inferred from validators. The type annotation is the contract; validators must agree.

The two contradictions (not equal sins, both rejected):

• = string.Empty on a required field (+ NotEmpty()) — forbidden, a real bug: JSON omission leaves "", NotEmpty() passes, silent wrong data.
• string? with unconditional NotEmpty() — discouraged, a smell: runtime behavior is right, but the annotation lies and disarms the compiler's null analysis.

The timewarp-architecture template enforces both at build time (TWA0002/TWA0003).

Also forbidden: = default! on non-generic reference types (use null!), and FluentValidation on Response (use ctor + Guard.Against.*; validation is for user-facing requests).

See nullability.md.

5. Apply mutability — accessor declares intent

Read-only display sharing across endpoints: get-only interfaces (e.g. IPolicyDto) — not bindable, not I*Details.

6. Response patterns — the discriminator is "has invariants"

required init is not a general alternative to ctor+Guard: it enforces presence at the construction site but checks nothing — new Response { RoleId = Guid.Empty } compiles and ships. If the field has any invariant (a Guid id that must be non-empty is one), use ctor+Guard.

7. Query-string queries

Implement IQueryStringRouteProvider + GetRouteWithQueryString() for optional filters. Optional filter properties are string? / nullable value types with no unconditional required rules. Compose generated helpers into the query string:

var collection = new NameValueCollection { GetAuthQueryParameters(), GetOpenDataQueryParameters() };
return $"{GetRoute()}?{this.GetQueryString(collection)}";

8. Validator

• Compose shared validators via SetValidator.
• Empty validator is valid: public sealed class Validator : AbstractValidator<Query>;
• Do not add isolated validator unit tests in the contracts test project — FluentValidation is tested at integration level.

9. Contract serialization tests (dedicated project)

Contracts are authored before the server exists (frontend-first, mock-backed BFF flow); a host-free serialization check is the only test that can run in that window. Prefer a co-located Jaribu *-tests.cs next to the contract (epic 145 north star; see create-role-tests.cs). Suite-shaped *contracts-tests projects are Jaribu MTP — assert with Shouldly only; do not reintroduce Fixie or xUnit.

Add SerializeAndDeserialize round-trips using ContractSerializationDefaults (camelCase properties; PascalCase string enums via JsonStringEnumConverter, integers rejected). Prioritize contracts where serialization can actually diverge: required/init members, custom converters, non-default constructors, enum properties, OneOf/SharedProblemDetails envelopes. Plain auto-property POCOs are low-priority once server integration tests exist. Do not use FluentAssertions (v8+ is commercially licensed).

10. Mock response factory (when mock mode needs it)

Add GetMockResponseFactory() on the contract + register it in the SPA mock service when SPA mock mode needs this endpoint — the mock service falls back to the real API for unregistered types, so factories are per-endpoint opt-in, not mandatory ceremony.

Detect the repo's mock pattern first: the canonical shape puts the factory on the contract and registers it in a Dictionary<Type, Delegate>; some solutions instead use standalone *MockFactory classes inside the SPA. Copying the wrong shape into a repo is a common agent error. See the tw-mock-response-factory skill.

Validation checklist

• public static partial class with nested Query/Command, Response, Validator
• [ApiEndpoint] on hosted operations; exactly one of [EndpointAuthorize] / [EndpointAllowAnonymous(reason)], always (TWA0013/TWA0014 enforce this)
• Hosted [EndpointAuthorize] Policy is a registered server policy (PermissionIds.* or an AddPolicy name) — TWA0024 flags drift at the server build
• Hosted [EndpointAuthorize] sets AuthenticationSchemes (task 161 — permission policies have no scheme list; Policies(...) alone authenticates only the host default scheme)
• [ApiRoute] with correct verb and route constraints ({Id:guid}, {Id:min(1)}, …)
• IRequest<OneOf<Response, SharedProblemDetails>> (TimeWarp.Mediator)
• Folder plural + repo's casing; namespace plural
• Bindable flows use I*Details + shared AbstractValidator<I*Details>; Command/Response declare the interface properties
• Nullability matches validator rules — no string? + unconditional NotEmpty() (TWA0002), no = string.Empty on required fields (TWA0003)
• No default! on non-generic reference types
• Response invariants enforced in ctor + Guard, not FluentValidation
• Mutability matches binding intent (set vs init/get-only)
• Serialization round-trip test in the contracts test project (prioritize non-trivial shapes)
• GetMockResponseFactory() registered if SPA mock mode exercises this endpoint

Common pitfalls

Canonical examples

• Living anchor (timewarp-architecture template): web/features/admin/roles/ — role-details-contracts.cs (IRoleDetails + validator, shared at slice root), create-role/create-role-contracts.cs, get-roles/get-roles-contracts.cs (attribute auth + open-data), get-role/get-role-contracts.cs (manual auth, I*Details Response). Each contract sits beside its handler in the same use-case folder (create-role/create-role-handler-application.cs); layer projects compose via static *-{layer}.cs globs regardless of folder.
• Inline reference implementations: examples.md.

Related skills

• tw-feature-placement — the filename grammar every -contracts.cs file follows (function segment dropped, escape hatch, registry, TWA0015/TWA0016)
• tw-mock-response-factory — GetMockResponseFactory() on contracts + SPA mock service registration
• tw-csharp — formatting and naming only; does not override contract nullability/mutability rules
• tw-blazor-layout / tw-blazor-css-strategy — UI shell and styling; contracts feed EditForm binding
• tw-slice-isolation — product-slice placement / TWA0009; contracts assemblies are free under TWA0009 (other assembly), but still use plural …Features.* namespaces aligned with the SPA product slices they serve
• Do not use dotnet-webapi for this contract pattern