design-first
Writing and reviewing an API’s contract, such as an OpenAPI document, before writing the code that implements it.
In more detail
Review at the design stage catches ambiguous names, missing errors and incompatible assumptions while they are cheap to fix. It does not freeze the design; it gives the implementation a visible promise to keep.
Related terms
- OpenAPI — A standard, language-neutral format for describing an HTTP API: its paths, operations, parameters, request and response schemas, errors and security.
- API contract — The written promise an API makes about its operations, inputs, outputs and errors, which callers rely on while the code behind it changes.
- source of truth — The one authoritative place a fact is recorded, from which every copy is derived instead of being maintained separately.
- code generation — Producing client or server code automatically from a machine-readable contract such as an OpenAPI document or a Protocol Buffers file.
Taught in
- OpenAPI And Design-First — Modern API Architecture: REST, GraphQL & gRPC
- API Contract Architecture: OpenAPI 3.1 & Schema Truth — Production Full-Stack Engineering