4 Describing an API with an API description format

This chapter covers:

  • What is an API description format
  • How to describe a REST API with the {name-oas} (OAS)

In the previous chapters, we explored how to design a basic programming interface using the information collected in the API goals canvas. We identified the resources, actions, parameters, and responses for our example Shopping API. We also designed the API’s data. But we did all of this using box-and-arrow diagrams and some tables.

Such figures and tables are always useful for brainstorming and getting an overall idea of how the API’s goals can be transposed into a programming interface. But when it comes to describing precisely a programming interface, and especially its data, it is simpler and more efficient to use a structured tool like an API description format. Being code-like and a standardized description of an API, this offers many advantages:

  • It notably facilitates the sharing of your design with anyone involved in your project.
  • It can be easily understood by people knowing this format and by any API documentation tools (among many others).

The {name-oas} (OAS) is a popular REST API description format. In this chapter, we will walk through its basics in order to uncover the benefits of using such a format.

4.1  What is an API description format?

4.1.1  Introducing the {name-oas} (OAS)

4.1.2  Why use an API description format?

4.1.3  When to use an API description format

4.2  Describing API resources and actions with OAS

4.2.1  Creating an OAS document

4.2.2  Describing a resource

4.2.3  Describing operations on a resource

4.3  Describing API data with OpenAPI and JSON Schema

4.3.1  Describing query parameters

4.3.2  Describing data with JSON Schema

4.3.3  Describing responses

4.3.4  Describing body parameters

4.4  Describing an API efficiently with OAS

4.4.1  Reusing components

4.4.2  Describing path parameters

4.5  Summary



Unfortunatly, we weren't able to load your books.

Unable to load book!

The book could not be loaded.

(try again in a couple of minutes) homepage