What is a breaking API change?

February 16, 2020

This is part of a multi-part series on how to version your API.

As previously discussed, the whole point of versioning is to manage change so you can evolve your API without breaking your client's implementation. In order to do this, changes that will "break" will your client's implementation warrant a new version. But what is and is not "breaking" can be tricky.

Is your change additive and backwards compatible?

In general, adding new "things" to your API should be considered safe. These include:

You should consider the specifics of your own API as every API has nuances. But it is reasonable to expect clients to implement in such a way that additions are simply ignored when they come online and implementation details are not hardcoded.

Conversely, changes that are clearly breaking or backwards-incompatible generally include modifying how things are represented.

Some examples include:

Some gray areas

In between the obvious examples, there are some tricky gray areas. For example, let's say your User records have a picture_url field which has always pointed to an S3 image and you wanted to host your images elsewhere. You could argue that a client shouldn't make any expectations about what that URL looks like...just that it points to an image. But you should be aware that clients may have hardcoded such an expectation and perhaps even for a legitimate reason (perhaps their code was operating behind a firewall and had white-listed S3).

It's in these situations that you should keep in mind Hyrum's Law:

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.

No, you it is not your job to prevent every client against hard-coding such implementation details, but it is your job to use your best judgement. Consequently, it is best to always provide comprehensive documentation, proactively communicate to your clients, and strive to make change less painful for your clients.