API Versioning

[ozanseymen]

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