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