When teams implement an API before agreeing on its design, consumers may discover usability problems only after code has been written. A design-first approach—also called specification-first or contract-first—iteratively creates an API definition before implementation. Treat the definition as a prototype: render it as documentation, mock its behavior, and ask prospective consumers whether it solves their problem. section 1.5.1
Move from an intended consumer outcome to an agreed implementation contract:
- Identify the capabilities and tasks consumers need. Align stakeholders on the API’s resource model, terminology, and operations before detailing the definition. section 5.2.4
- Create the OpenAPI definition and review it with consumers and colleagues. Include security mechanisms, breaking-change and deprecation policies, rate limits, and usage plans alongside functional behavior. section 1.5.1
- Make acceptance explicit—for example, by approving and merging a pull request or changing a review ticket’s status. Implementation should not begin while the agreed design is still in flux. section 5.5.7
Table 5.2 An API operations table for the Product Catalog API
|
Operation name
|
Operation Description
|
Participant
|
Web resource
|
Request
|
Response
|
|---|---|---|---|---|---|
listCategories
|
List all categories
|
Customer
|
Category
|
Filter by field, sort by field, order direction, page size, page cursor
|
Category
|
listProducts
|
List all products
|
Customer
|
Product
|
Filter by field, sort by field, order direction, page size, page cursor
|
Product
|
viewProduct
|
View a product’s details
|
Customer
|
Product
|
Product ID
|
Product
|
listProductReviews
|
List all reviews for a product
|
Customer
|
Review
|
Filter by field, sort by field, order direction, page size, page cursor
|
Reviews
|
viewReview
|
View a product review
|
Customer
|
Review
|
Product ID, Review ID
|
Reviews
|
The Product Catalog API operations table makes the proposed contract reviewable: each operation names its participant, resource, request, and response before implementation begins. section 5.2.4
Once the definition is agreed, backend developers can implement the service, testers can write functional tests, and client teams can integrate against a mock in parallel. This can shorten development lead time, but design review still needs human judgment about the consumer experience. A centralized queue of manual approvals can itself become a bottleneck and may miss problems. section 1.5.1 section 1.1
Design-first need not forbid exploratory code. When requirements or technology constraints are unclear, a team may prototype in code, generate a definition, and then refine that definition as the design. If implementation generates another definition later, compare it with the source-of-truth definition from the design phase and fix differences. section 6.3.2
