6 Describing HTTP operations with OpenAPI

This chapter explains how to describe HTTP operations with the OpenAPI Specification and why doing so accelerates and de-risks API design. It positions OpenAPI as the standard format for REST APIs that supports the whole lifecycle: enabling collaborative design discussions, linting and quality checks, documentation, testing, mocking, code and configuration generation, and gateway alignment. The chapter introduces working with OpenAPI in parallel to API design (not during needs analysis), clarifies specification-first versus code-first authoring approaches, and offers practical guidance on versions (favoring 3.1/3.0) and formats (YAML for human readability). It advocates starting with a minimal document and incrementally enriching it as HTTP choices are made.

Readers learn to map resources and operations to OpenAPI constructs: resource paths become keys under paths with human-readable summaries; path parameters are defined at the path level with name, in, required (true for path), and schema. Operations are added as lowercase HTTP methods under each path, each with a concise summary that mirrors the intent captured during design. Inputs are captured as non-body parameters (path, query, header) in a parameters list and as a requestBody for payloads, using description and content with an explicit media type to make them visible to tools. Throughout, the chapter emphasizes using summaries and descriptions to keep intent clear and aligning the specification with design artifacts while postponing fine-grained data modeling to the schema fields.

Outputs are specified per operation in responses, where each HTTP status code maps to a response object with a clear description; multiple outcome cases that share a status are merged when they return the same kind of data. Response bodies are described with content, media types (e.g., application/json), and schema (with descriptions kept next to the schema), while no-body responses like 204 omit content. Response headers are defined under headers, such as returning a Location header after resource creation. The chapter closes by reinforcing a disciplined, incremental workflow: begin as soon as resource paths are drafted, add methods and inputs/outputs as decisions are made, use the schema placeholders for later detailed data modeling, and eventually refactor shared elements to reduce duplication and improve maintainability.

Using a spreadsheet to describe our REST API was only to simplify our learning. We can describe the programming interface with OpenAPI once we start to design it.

An API Documentation tool can render an OpenAPI document and show information similar to our API spreadsheet but in a more user-friendly way.

YAML is a cousin of JSON with additional features, such as commenting.

All of the REST API information we put in our custom API spreadsheet can be described in a standard way with an OpenAPI document.

We design and describe the programming interface in parallel.

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

We describe HTTP operations with OpenAPI as we design them.

We can use OpenAPI to describe the HTTP representation of resources instead of the resource table of the API spreadsheet.

We can use OpenAPI to describe the HTTP representation of operations instead of the operation table of the API spreadsheet.

We add operations to the OpenAPI document when choosing their HTTP method.

In OpenAPI, input data is organized into body and non-body data (headers, path, and query parameters).

We add operation inputs to the OpenAPI document when choosing their locations in the HTTP request.

We add responses to the OpenAPI document when choosing their HTTP statuses.

We add output data to the OpenAPI document when choosing their locations in the HTTP response.

FAQ