This chapter covers:
- Informal vs formal descriptions.
- Learning about the OpenAPI specification.
- Learning about YAML.
- Describing our first GET operation.
OpenAPI definitions are at the heart of automating our API workflows. They are the slices of bread in a sandwich shop, the fruit on a breakfast buffet, and the vanilla in vanilla muffins. Which is my way of saying that they’re important.
When we formally describe an API we’re turning the idea of that API into some data which we call a definition. It differs from an informal description which has no strict rules or syntactical structure. Informal descriptions are akin to documentation found on websites, great for humans to read but hard for machines to decipher.
Once an API has been described into a definition it can be used by tools (cough machines), fueling different parts of the API ecosystem such as API request validation, code stubs, documentation and more.
PS: Machines shouldn’t have too much power if movies have taught us anything! However, they should be able to help us out just a little!
Warning
API Definitions both excite and propel me, and as such, I will continue to wax lyrical on the merits of API definitions. You’ve been warned!
If we were to look at where this fits in the scale of things, we could view it as such:
Figure 3.1. Mental model of OpenApi/Swagger, showing where definitions fit in.
