Breaking API Changes
Explore how to manage breaking API changes effectively by implementing versioning in request and response formats. Understand the pros and cons of different versioning strategies such as URL versioning, custom headers, and media types. Learn how to support multiple API versions side by side to maintain backward compatibility and reduce code duplication in your distributed system.
We'll cover the following...
Versioning
Nothing else will suffice. A breaking change is on the horizon. There are still things we can do to help consumers of our service.
The very first prerequisite is to actually put a version number in our request and reply message formats. This is the version number of the format itself, not of our application. Any individual consumer is likely to support only one version at a time, so this is not for the consumer to automatically bridge versions. Instead, this version number helps with debugging when something goes wrong.
API routes
Unfortunately, after that easy first step, we step right out into shark-infested waters. We have to do something with the existing API routes and their behavior. Let’s use the following routes from a peer-to-peer lending service (the service that collects a loan application for credit analysis) as a running example. It needs to know some things about the loan and the requester:
Table 1: Example routes
| Route | Verb | Purpose |
|---|---|---|
/applications |
POST |
Create a new application |
/applications/:id |
GET |
View the state of a specific application |
/applications? q = query- string |
GET |
Search for applications that match the query |
/borrower |