api-design

Scope

The contract an HTTP API exposes, and nothing about how it is implemented. Resource modelling, URIs, methods, status codes, representation shape, collections and their pagination, the error contract, concurrency and caching headers, long-running operations, versioning, compatibility judgement, deprecation, and the OpenAPI document that states all of it.

Applies whether the contract is new, being redesigned, or being reviewed before a release.

Not covered: