My Top 3 Tip for Handling API Versioning
Arguably, one of the most important steps of your API design process
When designing an API, how many times do you think of the versioning strategy before you write your first line of code? I’ll take a wild guess here and say most of you would say “never”.
And that’s fine! It’s counterintuitive to start thinking ahead of time about versioning when you don’t even have the first version ready.
However, you should.
Adding versioning into an already mature API requires a lot of work, however, if you at least have a strategy defined before you code it, you’ll know where to leave room for it so you can add it in the future.
Personally, I believe that whenever you start thinking about creating an API, you should, at least, consider the following:
API versions might introduce breaking changes, so make sure you have a standard way to make this clear. Semver for instance provides a very simple way to handle 3 categories of changes so your users will know what they’re getting themselves into when jumping from one version to the other.
You can’t only have one single version online. What happens if you jump from version 1 to version 2 and suddenly the schema of your data changes and you change the way 2 of your main endpoints work? Versioning requires you to have a strategy to release new ones while giving your clients enough time to adapt and adjust before the service they rely on is no longer compatible.
Do not try to re-invent the wheel when it comes to handling versioning. Use your channel’s standard ways, they’re there for a reason. For instance, if you’re going with an HTTP-based API, you have the Accept Header or you can put the version as part of the URL as well. Just make sure you don’t force your client applications to implement a non-standard way to request a specific version of your API. That would just make things more complicated for those developers and, potentially, prompt them to look elsewhere for the same functionality.
There is more to versioning but I don’t want to bore you and fill your inbox with a wall of text. If you want to know more, check out this article I wrote a while ago about API versioning.
Do you have any questions, would you like to leave a comment? Please, I’d love to read it!