Part 4 — Versioning RESTful APIs

Have you ever gone through that terrible feeling of developing an application, and suddenly it stops working because someone has updated the API version?

That’s exactly the “unpleasant” subject I’ll be talking about here.

If you develop or want to develop APIs, you can solve this with a simple solution called Versioning.

There are many ways of versioning your API, and in this article, I’ll show you the main ones:

Do you remember that gastronomy API example? Let’s use it here:

https://api.mygastronomy.com

If you haven’t read the first articles of this series, check it out:

• [1] An API RESTful’s anatomy
• [2] What you need to know about methods and status codes from HTTP Protocol
• [3] Security in APIs RESTFul

Now, let’s dive into APIs versioning:

URL Versioning

When versioning via URL, we have three different ways of doing it: subdomain, path, or query string.

On a subdomain model, you specify its version right in the beginning of your URL, for instance:

HTTP GET
https://api-v1.mygastronomy/wines

Please note I put “-v1” right after “api”. That specifies what version is being used, so for people consuming this API, it’s enough to change that subdomain when requesting something.

On a path model, you’ll specify what is the version right after your base URL, for instance:

HTTP GET
https://api.mygastronomy/v1/wines

This is one of the most used approaches, because, besides making the URL looking cleaner, it also makes browsing through different versions easier. That’s a dev-friendly approach when compared to others.

If you feel like being creative, you can specify your version via query string, for instance:

HTTP GET
https://api.mygastronomy/wines?version=1.0&country=brazil

Note that I specified the 1.0 API version and put the parameter via query string.

This has been widely used, but not that much nowadays. It makes versions browsing worse, and your URL gets harder to read, especially when there are many parameters on the query string.

Versioning via Header

The header versioning happens via HTTP content-type, that is, using “Accept” header on your request. For instance

HTTP GET
https://api.mygastronomy/wines
Accept: application/vnd.gastronomy.v2+json

If we follow this specification literally, that’s the proper way to version your APIs.

There’s also an approach when you use a custom header to specify the version, like the following:

HTTP GET
https://api.mygastronomy.com/wines
api-version: 2

Note that, in this case, I have created a new header called “api-version”, so the consumer must specify which is their desired version for that request.

The bright side of it is that your URL remains clean and untouched. This is not very dev-friendly though, because this request must be made with a great level of attention.

Best Practices

Versioning is one of the most widely discussed themes in the APIs community because specification itself doesn’t induce a good developer experience.

Because of that, my recommendation is taking what’s best in each approach, aiming at providing a great developer experience, which means that the versioning cannot be an obstacle for the ones that will consume the API.

On the other side, the API creator also needs a simple mechanism that facilitates DevOps concepts implementation, like Continuous Integrations and Continuous Delivery.

I like using versioning on the API via PATH because it’s responsible for the APIs structural stability and for bigger updating packages.

Adding a custom header to specify the sub-version date and is responsible for minor changes, like metadata fields, query string parameters, and things like that.

The request using this approach:

HTTP GET
https://api.mygastronomy.com/v1/wines
api-version: “2019–06–01”

Stripe uses this approach greatly. Check it here.

As I said, there is no perfect scenario for APIs versioning. It’s a discussion that, many times, is based on the developers’ personal point of view, so the best thing you can do is deeply understand your scenario and follow what makes more sense for you.

If you want fewer problems with that, make use of an API Management platform to help you with that.

That’s it, I hope you all have liked it, and see you in the next article!