4 Breaking change checks: Managing API evolution

 

This chapter covers

  • Running breaking change checks
  • Using API versioning schemes
  • Defining a breaking change policy

At the design stage of your API product, your API team iterates on your API design and updates your OpenAPI definition files. It’s useful to know whether any change your team introduces isn’t backward compatible. In this chapter, I show how to use API diff tools to understand API definition file changes and how to detect which of them are breaking changes. One way to avoid introducing breaking changes to existing API consumers is API versioning, and I discuss different API versioning schemes and scopes used by different organizations. I also explain the costs of introducing new API versions and how you can communicate your API change management approach to consumers using a breaking change policy document. I end the chapter by providing some tips on managing breaking changes in your workflow. The topics covered in this chapter will be of importance to both API developers and API product managers and owners.

If you’ve followed the instructions in section B.8 of appendix B to set up the API tools, then you have the Tufin/oasdiff tool installed for the exercises in this chapter. To work on the exercises in this chapter, navigate to the chapter4 directory in this book’s code repository at https://github.com/apiopsbook/apiops.

4.1 API definition changes in your APIOps workflow

 

4.2 The problem of understanding what changed

 
 
 

4.3 API diffs

 
 

4.4 Detecting breaking changes

 
 

4.5 Generating API changelogs

 
 

4.6 Breaking changes and API evolution

 
 
 

4.7 API versioning schemes

 
 
 

4.7.1 Path-based versioning scheme

 
 
 
 

4.7.2 Hostname-based versioning scheme

 
 

4.7.3 Query string-based versioning scheme

 
 

4.7.4 Custom-header versioning scheme

 
 

4.7.5 Accept header versioning scheme

 
 
 

4.7.6 Pinned versioning scheme

 
 
 
 

4.7.7 No versioning scheme

 

4.7.8 Combination of various schemes

 
 

4.8 API versioning scope

 

4.8.1 Global versioning scope

 
 
 

4.8.2 Per-resource versioning scope

 
 

4.8.3 Per-endpoint versioning scope

 
 

4.9 API versioning identifiers

 
 
 
sitemap

Unable to load book!

The book could not be loaded.

(try again in a couple of minutes)

manning.com homepage
test yourself with a liveTest