chapter five

5 Describing API responses

 

This chapter covers

  • Learning about JSON Schema and how to describe data
  • Describing the 200 response of GET /reviews
  • Adding the response definition piece into our FarmStall API

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).

5.1 The problem

5.2 JSON Schema and the mind-blowing world of data schemas

5.2.1 JSON Schema

5.2.2 Type

5.2.3 Minimum and Maximum

5.2.4 Number vs Integer

5.3 Status Codes

5.4 Media Types (aka MIME)

5.5 Describing GET /reviews response

5.5.1 Smallest response in OpenAPI

5.5.2 GET /reviews 200 response body

5.5.3 Adding rating into our response body

5.5.4 Describing message, uuid and userId

5.5.5 Schemas

5.6 Summary