API responses

← Back to concept

A response is a public contract

Use stable, typed response shapes. Validate external data at the boundary. Keep ownership identifiers, revision fields, pagination and error semantics intentional and documented.

An API adapter reports transport failures without deciding how the UI presents them. A domain interprets expected results; the application boundary chooses navigation or messages. A successful HTTP status must not hide malformed required data.

Change a public response only after finding all consumers. Update serializers, generated types, mocks and behavioral tests together. Media serializers return relative storage paths rather than leaking the host of an internal server request.