Where should I put my API version?

February 24, 2020

This is part of a multi-part series on how to version your API.

After having discussed how to represent your version, the final question is naturally then where to represent that version.

Option 1: In the path

A common place to put the version is in the path:

http://acme.com/api/v1/posts
Pros

The API version is front and center. This will make it easier to debug and make it less likely for someone to be on the wrong version.

The API version is explicit. There is no default behavior and no ambiguity about which version a client is requesting.

Routing is easier. By placing your version early on in the path, you will most likely be able to have some nice, straightforward branching logic in your routes.

Cons

It only works well with simple integer versions. It also results in longer, arguably more cluttered URL.

Option 2: As a query parameter

Another place is as a query param:

http://acme.com/api/posts?version=1
Pros

Potentially easier for the client. Assuming you default to the latest version if no query param is passed, clients who are using the latest version (hopefully most) have to do less to construct the URL.

Cons

Doesn't really work with query params as you shouldn't pass query params in with POSTs. It is also less explicit: if your default version changes one day and you haven't given plenty of warning, some client implementations might break.

Option 3: As a header

Finally, you can put the version as a header

http://acme.com/api/posts

API-Version: 1
Pros

The API version is explicit, just like option 1

The URL is cleaner. This may be more aesthetics but your API will feel less cluttered.

You can put non url-friendly characters in your version if you wish

Cons

The version is less front-and-center now that it's in a header. Also, debugging GETs is a little more difficult since you can no longer just copy/paste something in the URL of your browser.

Conclusion

I think the explicitness of option 1 and 3 are most important. I generally push for option 3 but arguments could be made either way.