Design-first approach
A specification-first approach defines and validates an interface or behavioral contract before implementing the system that conforms to it.
Automating API Delivery
An API development practice that iteratively creates and validates an API definition before implementing the API in code.
- How it is used
- Establishes an agreed API definition for consumer validation before implementation and for parallel backend, testing, and client work afterward.
- How deep it goes
- Describes iterative definition, mocking, review, approval, and implementation handoff, without prescribing a single universal design-review procedure.
- Examples
- Uses a Product Catalog API operations table and approval by pull-request merge or review-ticket status change.
- What you can do after
- Practice/perform consumer validation and explicit design approval before coordinating parallel implementation against an agreed API definition.
Read how Automating API Delivery explains design-first approach →
Spring Start Here, Second Edition
A contract-first approach develops an API by specifying its interface before implementing the endpoint and generating implementation artifacts from that specification.
- How it is used
- Defines a REST API contract before endpoint implementation and generates part of the implementation from that specification.
- How deep it goes
- Defines contract fields and shows endpoint generation, but defers detailed instruction on using OpenAPI.
- Examples
- Uses a Payment API contract for POST /payment, with a PaymentDetails request body and response schema.
- What you can do after
- Build it from scratch by defining an OpenAPI contract and generating part of a Spring endpoint implementation.
Read how Spring Start Here, Second Edition explains design-first approach →
The Design of Web APIs, Second Edition
A specification-first approach is an API development method in which the API specification is authored before or alongside implementation code.
- How it is used
- Guides API decisions about consumer experience and constraints before implementation begins.
- How deep it goes
- Defines design-first and contrasts two ways to author OpenAPI, with practical trade-offs rather than a complete design procedure.
- Examples
- Uses a /products resource path and OpenAPI paths, post, requestBody, and responses entries to illustrate documenting an operation.
- What you can do after
- Practice/perform API design before implementation and choose an OpenAPI authoring approach suited to the context.
Read how The Design of Web APIs, Second Edition explains design-first approach →
What to know first
- OpenAPI specificationThe OpenAPI Specification is a machine-readable standard for describing HTTP APIs, including their operations, inputs, outputs, data structures, and security requirements.
Related concepts
- code-first approachcontrasts with · A code-first approach defines a system, model, or contract in source code before deriving or finalizing its schema or specification.
- OpenAPI specificationuses · The OpenAPI Specification is a machine-readable standard for describing HTTP APIs, including their operations, inputs, outputs, data structures, and security requirements.
- APIOpspart of · APIOps is the practice of automating the governance, delivery, and operation of API products across their life cycle.
- API-first approachcontrasts with · An API-first approach treats APIs as primary interfaces or products by defining their contracts before or independently of the implementations and consumers that rely on them.
Questions about design-first approach
What is design-first approach?
A specification-first approach defines and validates an interface or behavioral contract before implementing the system that conforms to it.
Which Manning books explain design-first approach?
Automating API Delivery, Spring Start Here, Second Edition and The Design of Web APIs, Second Edition.
What should I know before learning design-first approach?
Manning books that teach design-first approach usually introduce OpenAPI specification first.
What is the difference between design-first approach and code-first approach?
A specification-first approach defines and validates an interface or behavioral contract before implementing the system that conforms to it. A code-first approach defines a system, model, or contract in source code before deriving or finalizing its schema or specification.
What kinds of design-first approach are there?
Kinds of design-first approach include ADDR process.
What is design-first approach part of?
Design-first approach is part of APIOps. APIOps is the practice of automating the governance, delivery, and operation of API products across their life cycle.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.


