Data makes the world go round …or maybe that’s money?
In this chapter we’re going to describe a simple HTTP response with OpenAPI and add it to our FarmStall API definition. Responses are the fuel for consumers and they can be large/complex. Describing them is an important part of communicating an API.
An HTTP response is made up of three things. A status code, a set of headers and an optional body. We’re going to focus on the status code and body for now and leave response headers for another chapter.
A response definition in OpenAPI needs at least a status code and a description. If there is a response body it must include at least one media type (eg: application/json).
Response bodies are where it’s at though. All the exciting bits. To describe the shape of the data OpenAPI adopted the JSON Schema (v4) [7] specification. Which was designed to describe what goes into a JSON document but with a few tweaks can describe XML and FormData as moderately well too. This format blends seamlessly with the rest of OpenAPI but there are proposals to include external specifications for describing data in newer versions of OpenAPI… watch this space!
Here is a quick glance at a sample response definition…
Listing 5.1. Example response definition
responses:
200: #1
description: A human description #2
content:
application/json: #3
schema: #4
type: object
properties:
# ...
Let’s learn more about describing data!