Part 1 Describing APIs

Before we start our journey into API design, we should get comfortable describing the existing world around us. Therefore, in part 1 we’ll look at how to describe an existing API using OpenAPI and Swagger. The API we’ll use, FarmStall, is hosted online and was created specifically for this book. It’s a little contrived but functional.

Chapter 1 will start by discussing the fundamentals of APIs and what OpenAPI is, provide a refresher on YAML, and go through each step that would lead up to a fully described API. We’ll then introduce tools like Postman (chapter 2) and Swagger Editor (chapter 4), and end up hosting a real API documentation website with Swagger UI (chapter 8). Areas of the API we’ll describe include requests and responses (chapter 5), bodies, query parameters, authentication, and authorization (chapter 7).

By the end of part 1, you’ll be able to describe real APIs in the wild, albeit with a limited vocabulary that we’ll further develop throughout the book.