Let’s face it: you will at some point have to introduce breaking changes to your API. Most of us plan for this, and try to mitigate the consequences, by versioning. There are loads of ways people out there are versioning – introducing a new subversion with every minor change, bundling changes into major version releases, using content negotiation to manage different versions of resources, etc – and people bicker to no end about the best way to do this. But if one thing is becoming clear,¹ it’s that the way you version your API doesn’t matter – the way you communicate does.

Good communication with your consumers is the key to easing transition to and adoption of new iterations of your API, and this means:

• Be transparent about how you are going to version (or not version) your API from the beginning.
• Let your consumers² know well in advance what changes you’re about to introduce (and maybe even say why!).
• Keep older versions around long enough for transitions and communicate a lot about deprecation – and even keep tabs on who is still using those older versions so that you can communicate with them directly about getting them up to speed with your latest API.
• Be active in any open source communities maintaining libraries for or using your APIs, at least to open issues letting them know the details of upcoming changes.

For those of us shouting “Hypermedia! Hypermedia!” as an alternative to versioning, or at least as a helpful hand in the process: yes, the goal of hypermedia and RESTful architecture is to allow systems to evolve after they are already deployed gracefully, so that the API exposes new behavior through hypermedia and clients execute this on the fly.³ This would be awesome – if our clients are actually written to consume hypermedia like this. But the fact is, most clients aren’t, and even if hypermedia practices were mainstream, if you have an open API, you have no clue who your consumers are and/or how they’re consuming your API. If you make changes to a resource and expect hypermedia clients to be able to keep up, you’re ignoring any devs out there who might not be using hypermedia clients. If you communicate about these changes in advance, at least those folks will have a chance to prepare and catch up.

You’re never going to keep all of your API consumers happy:⁴ you’re going to break things, you’re going to expect they consume your API in specific ways or for specific purposes, and you’re going to be wrong. The only way to minimize breakage and maintain happiness in your community is transparency and proactive communication.