Get hands-on experience with 20+ free Google Cloud products and $300 in free credit for new customers.

API Versioning

Hi Community,

I am working on API design for a customer but we seem to got stuck on versioning.

So far we have concentrated on the following options - note that I am not intending to document every single pros and cons here:

Version in URL:

https://api.company.com/v2/collection/id

Pros:

  • Asserts mandatory version number
  • Easy to use
    • Immediately visible
    • Browser friendly
  • Seems to be the most popular choice out there, google search, twitter, linkedin, etc.

Cons:

  • URI to represent the entity - not the version of the entity.
  • When version is changed, URI for the same resource changes.
  • If resource is being versioned - not the API, then version number seems to be in incorrect place in URL hierarchy.

Accept header (vendor extensions):

Accept: application/vnd.company.v2+json

Pros:

  • Seems to be the philosophical favourite
  • Allows resource level versioning

Cons:

  • Doesn’t seem to be used much by top API providers - perhaps I am missing it.
  • Doesn’t solve the problem if API behavior is changed, rather than the resource representation. Accept header in HTTP spec talks about media type/range. E.g. /collection1 returns a list of 50 resources. Now collection retrieval and filtering logic has to change and now it will return 100 resources - including new 50 that weren’t included in the results before. Server behavior is changed in such a way that response is not backwards compatible. Resource representation is still same - it is still v2.json.
  • Doesn’t assert mandatory versioning
  • Not easy to use:
    • Not immediately visible
    • Not browser friendly

Custom header:

X-API-Version: v2

Pros:

  • Handles representational and behavioral versioning needs
  • Seems to solve cons of other solutions - introduces new ones though
  • Allows resource level versioning

Cons:

  • Custom implementation and custom handling from consumers
  • Needs work to integrate into existing HTTP model, e.g. caching vary.
  • Doesn’t assert mandatory versioning
  • Not easy to use:
    • Not immediately visible
    • Not browser friendly

Item 2 overrides the meaning of the Accept header to include representation (media type/range) and behavioral versioning. Contrary to that, Item 3 introduces a whole new custom header.

I am interested to hear which option community is leaning towards. Which option are you using to version your APIs?

Cheers

2 6 4,757
6 REPLIES 6