Design-first approach

As explained in 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.

A specification-first approach authors an independent OpenAPI document before or alongside implementation, making the document an editable source of truth for the API. section 6.2.1 section 6.2.2

Choose the approach by weighing these practical consequences:

• Check implementation against the specification and prevent an API gateway from exposing undocumented extra operations. section 6.2.2
• Edit and discuss OpenAPI without setting up or deploying a development framework. section 6.2.2
• Prefer code-first when automatic alignment with implementation outweighs the risks of unnoticed changes, framework limitations, or early stack decisions. section 6.2.2

Describing a resource path

Begin an OpenAPI document while designing a resource such as /products. Define the path, lowercase HTTP operation, parameters, request body, response status, headers, content, schemas, and human-readable descriptions. section 6.9

Figure 6.6 When deciding between specification-first and code-first approaches, it’s essential to check the pros and cons of each approach in the context in which you work.

Compare specification-first and code-first trade-offs against the constraints of your team, delivery process, and API lifecycle. section 6.2.2

How The Design of Web APIs, Second Edition covers it

How deep it goes

Explains source-of-truth trade-offs, editor selection, and document structure, but defers implementation-framework details.

Examples

Uses /products, OpenAPI editors, Swagger Editor Next, and a comparison of specification-first and code-first trade-offs.

What it assumes

Assumes basic API design and HTTP concepts while introducing OpenAPI authoring, structure, and editor-based validation.

What you can do after

Author and evaluate an OpenAPI contract independently, then use it to check exposed operations and document HTTP behavior.

How it connects

Connects OpenAPI with design-first, code-first, API gateways, resource paths, HTTP operations, and data modeling.

liveBookmanning.com

Read The Design of Web APIs, Second Edition on liveBook Get the book at manning.com

Also explained in

• 

  liveBookmanning.com
  Automating API DeliveryAn API development practice that iteratively creates and validates an API definition before implementing the API in code.

Compare how 2 books explain design-first approach →

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 standard, machine-readable format 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 architecturecontrasts with · An approach that treats APIs as primary product interfaces by specifying their contracts as a foundation for implementing the services and clients that use them.

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.