1 Introducing APIs and OpenAPI


This chapter covers

  • Describing an API ecosystem
  • What OpenAPI and Swagger are
  • When to use OpenAPI
  • An overview of this book

In this chapter we’ll take a look at the world of APIs and OpenAPI so we can give you an overview of the topics covered in this book. We’ll start by looking at the benefits of describing an API, at how these descriptions form part of an API ecosystem, and where OpenAPI fits in. We’ll look at an example of an OpenAPI document and see when to use OpenAPI in practice. Let’s get started.

1.1 What is an API ecosystem?

We like the word ecosystem. It describes the interactions and relationships between living and nonliving things within a fully functioning environment. We like to picture a wetland pond with frogs, wild grasses, and stones for some reason, but you may imagine something a little different—either way, the principle of an interactive, symbiotic system remains. If we borrow (cough, maybe steal) this principle from biology, we can use it to describe the world of APIs within a team or organization:

1.2 Describing things

1.2.1 Bridget’s task

1.2.2 The potential of Bridget’s solution

1.3 What is OpenAPI?

1.3.1 Example OpenAPI definition

1.4 Where do OpenAPI definitions fit in?

1.5 What is Swagger?

1.6 What about REST?

1.7 When to use OpenAPI

1.7.1 For API consumers

1.7.2 For API producers

1.7.3 For API designers

1.8 This book