5 Describing API responses

In this chapter we’re going to describe a simple HTTP response with OpenAPI and add it to our FarmStall API definition. We’ll look at the components of an HTTP response, comprising three parts: a status code, a set of headers, and an optional body. We’re going to focus on the status code and body for now (see figure 5.1). Headers will be covered incrementally throughout the next chapters.

Describing response bodies is an important part of communicating an API. Consumers need to know what the API will return when they call it from their applications.

5.1 HTTP responses

When describing a response in OpenAPI, you’ll need at least a status code and a description. If there is a response body, it must include at least one media type (such as application/json). Response bodies are where all the exciting bits are.

5.2 The problem

5.3 The mind-blowing world of data schemas

5.4 JSON Schema

5.4.1 The type field

5.4.2 Adding a field to an object

5.4.3 The minimum and maximum keywords

5.4.4 Number vs. integer

5.5 Status codes

5.6 Media types (aka MIME)

5.7 Describing the GET /reviews response

5.7.1 Smallest response in OpenAPI

5.7.2 The GET /reviews 200 response body