Breaking API Changes

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: