4 Describing an API with an API description format
This chapter covers
- What an API description format is
- How to describe a REST API with the OpenAPI Specification (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 OpenAPI Specification (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.