When building an API, you’ll need versioning sooner or later.
Let’s get to the point!
Why do I need API Versioning?
Backwards Compatibility
If you’re upgrading your API, It’s kinda nice to let the consumers know about the changes…right? I mean it would be very frustrating when something changed and there is no way of knowing it. That’s why we use API versioning and bump the major version if a breaking change in the API is introduced.
Clarity
Versioning your API gives you a reference point on where your API currently is. Going from V1 to V2 can be seen as two separate services, the big version bumps usually indicate a significant milestone in the code base of the API. A good way to work to your goal and a clear view what a specific version holds. Assuming the API has some decent documentation of course :)
Best Way To Apply API Versioning?
REST doesn’t provide for any specific versioning guidelines but the more commonly used approaches fall into three categories:
URI Versioning
You might’ve seen this before where the URL holds the version
api.chicken.com/v1
apiv1.chicken.comV1 could be a timestamp, a name, or anything else. Just be sure that the team agree’s on a uniform name.
Versioning using Custom Request Header
A custom header (e.g. Accept-version)
Accept-version: v1
Accept-version: v2Versioning using Accept header
Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0It’s important to know that an API will never be completely stable in the real world. So It’s important to manage these changes properly.
Think first, code later!😉
