20 Versioning an API and handling breaking changes

 

This chapter covers

  • Changing an API and understanding the impact of changes
  • Supporting multiple versions of APIs and schemas
  • Avoiding breaking changes

We added support for multiple pets and pets other than dogs in chapter 16. In the OpenAPI definition for the PetSitter API, the Job schema had a property changed from dog to pets. José noticed that this had a knock-on effect with Max, the frontend developer. If Nidhi had released the backend change before Max was ready, a large portion of the PetSitter website would have stopped working. But because the team communicates often, this was hardly a problem—they could easily coordinate how to roll those changes out. But what will happen when the API is made public? How can those breaking changes be avoided? And if the team makes such changes after outsourcing the mobile project, how would that be handled?

In the team’s case, they have a small and easily managed API between the frontend and backend, as well as between José’s team and the mobile developers, but as it grows to include more consumers (and more developers), things will get harder to manage. After they release the API to the public, they won’t have that control anymore and will need to be considerate when making changes.

20.1 The problem

20.2 What is a breaking change?

20.3 Releasing a breaking change

20.3.1 Coordinated breaking changes

20.3.2 Multiple API versions

20.3.3 Using media types to version operations

20.3.4 Adding and deprecating features

Summary