10 Creating an API design using OpenAPI

 

This chapter covers

  • Creating reusable schemas in OpenAPI
  • Converting the PetSitter domain model into schemas
  • Designing an API following the CRUD approach
  • Creating paths and operations for the PetSitter API

In the previous chapter we got to know José and his team, who are building the PetSitter application. We accompanied them through their initial meeting, in which they created an action plan for building the application. We also joined their domain-modeling whiteboard session, in which they prepared a high-level domain model.

The domain-modeling session was the first item on their action plan, which leaves us with the following steps:

  1. Max, the frontend developer, will create the first draft of their API design.
  2. Nidhi, the backend developer, will review that draft.
  3. Both will agree on finalizing the specification, or make edits and review again as necessary.
  4. Both will work independently on their parts of the implementation.
  5. After completion, they will integrate their code.

In this chapter, we’ll go through the first of the remaining steps.

10.1 The problem

In the previous chapter we created a domain model. That model is an informal, high-level representation of the concepts underlying the PetSitter application. Later, in the implementation stage of the project, we will develop frontend and backend parts, connected with an API. We now have to bridge the gap between those two, and we’ll do this with the formal description of the API using OpenAPI.

10.1.1 Converting a domain model to OpenAPI

10.1.2 Ensuring reusability

10.2 Creating the schemas

10.2.1 Starting an OpenAPI file with schemas

10.2.2 Referencing common schemas

10.2.3 The User schema