Breaking Changes in APIs

Originally published on Tumblr.

When changing an API, is there anything worse than a breaking change, i.e., a change that is incompatible with the existing version, and therefore potentially breaks client software?

It would be great if we never had to worry about breaking changes, but we do. Sometimes, even API designers make mistakes, sometimes out of carelessness, and sometimes because of their inability to predict the future.

There are 3 ways of dealing with these kinds of mistakes:

1. Ignore them.
2. Update the API and force clients to change their software.
3. Version the API.

Let’s start with versioning.

Versioning an API means creating a whole new instance of that API so that old clients using, say, version 1.0, won’t be affected by the incompatible change introduced in 1.1. That’s good for everyone, except the maintainers of the backend who have to support both APIs until the old one is retired. If new versions are introduced frequently the backend work can become a nightmare.

Updating an API and forcing clients to change their software is only possible when an API is in its infancy. At that point, introducing an incompatible change may be embarrassing, but could ultimately be less costly that versioning. This kind of change requires a high degree of communication with the client developer community. The reasons behind the change should be clear to everyone, and its rollout well coordinated.

The third option is often, surprisingly, the best option. Sometimes mistakes are best documented and fixed at a later date.

The OP3Nvoice API was released into private beta on March 21st. A month later we’d received enough feedback to realize that we could greatly simplify the API, eliminating nearly 50% of its functions, by making a significant breaking change. We decided to move forward with the change because:

1. We had a manageable number of clients (14), so communicating the change wasn’t difficult.
2. The simplification was a huge win for current and future clients.
3. We could temporarily make the change transparent to almost all clients.

From most points of view, this decision was a “no brainer”. The worst aspect was the embarrassment of admitting that our original design was flawed so soon after releasing our first implementation. Embarrassment is quickly forgotten, while the pain of maintaining multiple versions of an API is felt for a long time. In this case, I’m convinced it was the right choice.

When we have to confront our next potential breaking change, we may well take another path. I’ll report.