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 is useful to know if any change your team introduces is not 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 discuss 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 have 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.