Learn the vocabulary of describing an API in a standardized, machine-readable format.
0 / 5 completed
1 / 5
At standup, a dev mentions writing a machine-readable document describing an API's endpoints, request formats, and response schemas, which tooling can use to generate documentation and client code. What is this document called?
An OpenAPI specification is a machine-readable document, typically written in YAML or JSON, that describes an API's endpoints, request formats, and response schemas in a standardized structure. Tooling can parse this specification to automatically generate documentation, client SDKs, and even mock servers, rather than each of those being hand-built separately. It's become the de facto standard for describing REST APIs in a consistent, tool-friendly way.
2 / 5
During a design review, the team wants to automatically verify that an API's actual responses match what the specification promises, before merging a change. Which capability supports this?
Contract testing against the OpenAPI spec automatically verifies that an API's actual request and response behavior matches what the specification describes, catching a mismatch before it reaches production. Manually inspecting every response by hand doesn't scale and is easy to skip under time pressure. This automated check keeps the specification trustworthy as a source of truth that client code and documentation can safely rely on.
3 / 5
In a code review, a dev notices the specification defines a reusable schema component that's referenced by multiple different endpoints instead of being redefined separately each time. What does this represent?
Schema reuse via shared components defines a data structure once and references it from every endpoint that uses it, rather than duplicating the same definition repeatedly throughout the specification. This keeps the specification consistent, since a single update to the shared schema automatically applies everywhere it's referenced. Duplicating the same schema separately in multiple places risks the copies drifting out of sync as the API evolves.
4 / 5
An incident report shows a client integration broke because the API's actual response format changed without the OpenAPI specification being updated to match. What practice would prevent this?
Treating the OpenAPI spec as the source of truth, and requiring any API behavior change to update it in the same change, keeps the specification an accurate, trustworthy contract. Assuming client integrations adapt automatically to an undocumented change ignores that consuming code was built against the previously documented contract. This discipline is what makes generated documentation and client code reliably match the API's actual real-world behavior.
5 / 5
During a PR review, a teammate asks why the team maintains a formal OpenAPI specification instead of just documenting the API informally in a shared doc. What is the reasoning?
An informal shared doc written in prose can't be automatically parsed by tooling to generate client code, validate responses, or produce interactive documentation. A structured OpenAPI specification enables all of that automation directly from a single source. The tradeoff is the discipline required to keep the specification itself accurate and updated as the API evolves.