The Ultimate Guide to API Versioning

Sort of. Not versioning is not the same as not changing. We agree that considering whether a change is really needed is good – but as you’ve rightly noted, change is inevitable.

We agree that one needs to plan for change. Where we may differ is on the focus on versioning. Change is inevitable. But don’t push the cost and effort of all changes to API clients – which is what most change and versioning schemes seem to do.

The real intent of the “don’t version” notion is to plan for changes without breaking existing clients. Noted in the “API Versioning” blog and in your post is to commit to non-breaking changes. And if that cannot be done, fork the API and support both/all. From the blog I referenced:

If you know you need to introduce a breaking change, fork your API and release it in a new URL space. Call that a “version” if you like. You’re still not James Bond though, so be aware that releasing new versions does not give you license to kill the old ones.

The versioning schemes that API clients will object to are those that force a change to something (URL, header) simply because the version number changed. Indeed, I’m working with one right now that is going to force a URL change every 3 years, even if the API itself offers nothing new for what we need.

Edit: An example of an API that changes without breaking existing stuff yet adding new functions, there is an API (XML over HTTP) that has been in use for 10+ years. It does not use a version number anywhere and have 30+ sets of revisions in that time. We’ve never had calls we’ve been using break due to changes nor had to make “administrative” changes to keep up with a version number. The only time we’ve changed is to use new objects/fields/functions. They always add, never take away. It is possible to do. :slight_smile:

1 Like