When an API reference promises a response field that the live API omits, consumers cannot rely on the published contract. The OpenAPI Specification (OAS) provides a shared, machine-readable way to describe an HTTP API before implementation and check it afterward. OAS is the standard; an OpenAPI definition is a YAML or JSON file describing a particular API. section 6.1 section 1.4
A definition describes operations, expected requests and responses, and security mechanisms. OAS can describe an HTTP API whether or not it is RESTful. It is not the same as JSON:API, which prescribes how to design a REST API; an API following JSON:API can still be described in an OpenAPI definition. section 1.4 section 3.2
Figure 4.3 Top-level structure of an OpenAPI document structure
Use the document-structure diagram to locate the root OpenAPI object before following paths to path items and operations. section 4.2
Treat the definition as a working contract throughout delivery:
- Design it first, then render documentation or mock the API for consumer feedback before writing the backend. section 1.5.1
- Keep it in Git and review changes through pull requests. Run automated linting against design rules; reserve human review for questions such as resource models and operation design. section 1.5.2 section 1.7
- Compare definition versions for breaking changes, generate server or client code where useful, and test the running API against the agreed operations and response schemas. section 1.6 section 1.5.4
- Publish API reference documentation from the authoritative definition, and update that definition when requirements change. section 6.1 section 6.2.5
Find and prevent contract drift
Suppose GET /v1/catalog/products/{id} declares keywords mandatory, but the live response omits it. A rendered reference repeats the promise; it does not prove the server meets it. Update the authoritative definition when requirements change, generate controller code from it where appropriate, and run conformance tests against the implementation. For design-time feedback, a Spectral ruleset in VS Code can highlight violations directly in an OpenAPI file. section 6.1 section 1.5.4 section 3.5
Automation checks what can be expressed as rules or tested against a running API; it does not replace consumer feedback and design judgment. Hand-writing YAML can also be slow, so choose editing tools that integrate with the Git repository holding the primary definition. section 1.7 section 1.8
