How to version your API
February 26, 2020
This is part of a multi-part series on how to version your API.
We are wrapping up our multi part series on versioning with a summary of our recommendations.
Feel free to look through the previous blog posts for a more in-depth
The Recommended Playbook
We mentioned Stripe when discussed using dates to version your
API. We are big fans
of how they do it and endorse most of their versioning standard.
Here are some specifics:
- Version from day 1. As discussed previously, there should be no ambiguity
about which version is being requested and by starting out with a versioning
strategy, you won't paint yourself in a corner.
- Require every request have a version. This is one slight difference with
Stripe which allows a client to set their default, "global" version in their
UI. Setting an organization-wide API version makes sense for more sophisticated products with some background behavior that is not directly tied to an API request (such as a webhook). However, for most APIs, simply requiring a version on every API request suffices and is explicit and simple.
- Use a date to version your API. As previously discussed, dates seem to play
nicely with a philosophy of rolling, manageable iterations to your API. And
they also are naturally incrementing.
- Put the version in the header. As discussed previously, keeping the version out of the URL keeps your URLs less cluttered, particularly if you are versioning with a date. A simple
ACME-Version header should do just fine.
- Keep your versions a manageable size and scope. Perhaps you come up with some
rules of thumb such as, "It should take a client developer no less than X number of dev
time to update versions." Obviously X should vary per project, but the goal is a
consistent, stream of non-intimidating changes. Smaller, less-intimidating
changes will actually allow you to evolve your API faster and help prevent
clients getting "stuck" on certain versions.
- Come up with a commitment to a deprecation schedule and stick to it. For
example, you could commit to supporting the current version and the previous
version. Or you could commit to giving clients a year to upgrade once you cut a
new version. You'll need to come up with specifics, but by advertising such a
commitment up-front, you'll put prospective clients at ease and ensure alignment
with them from day 1.
- Proactively communicate changes. Update your documentation, send emails, do
whatever you think is best to be explicit about what's new, what's old, and
what is losing support.
- Keep a changelog in your documentation. Highlight breaking and non-breaking
changes making the breaking changes particularly explicit.
And that's it! We hope these blog posts help you build a better API and manage
it's evolution with the right versioning strategy your product.