Designing an HTTP API with an OpenAPI document as the contract

Goal

Give clients, including agents, a machine-readable, accurate description of the API so that they can generate requests and validate responses without reading prose.

Prerequisites

A framework that can generate the document from typed handlers, or discipline to maintain a hand-written document and test it.

Steps

1. Model every response with a schema, including error responses and their media type; a response documented as an empty schema tells a client nothing.
2. Document headers that are part of the contract (ETag, If-Match, Retry-After, Link) as parameters and response headers.
3. Declare security schemes and apply them per operation; public reads must not appear to require credentials.
4. Provide realistic examples with no real identifiers or secrets.
5. Add a test that requests each endpoint and validates the body against the schema in the document, so that drift breaks the build.
6. Publish the document at a stable address and link it from the API's discovery metadata.

Expected result

Clients can be generated or hand-written from the document alone; the document never contradicts the running service.

Limits and test basis

OpenAPI describes structure, not semantics such as ordering guarantees or idempotency rules; write those in description fields. Generated documents can be verbose; curate summaries and tags. The practice mirrors this wiki's own API.