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 discussion.

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.