re: Real World Developer's Problems: API Versioning VIEW POST


Hi Jonathan, good post, this is a rarely-examined issue when creating REST APIs. My view is:

Specify the version putting it on the URI:

This approach isn't RESTful as we are having multiple URNs for the same resource, which breaks REST constraints for resources

Using a custom request header:
*Accept-version: v1*

Caching becomes difficult, so for that reason I reject this.

Adding to the HTTP Accept header
*Accept: application/json; version=*

I think this is the best approach because it separates versioning and media types without requiring an extra header and it keeps the URI clean. On the downside, it's more difficult to parse the Accept header and it requires more work server-side, but IMO the positives outweigh the negatives.


Could you please elaborate on why using a custom request header makes caching a difficult thing to achieve?


Hey Andrei, it's too long to properly describe in a reply but in a nutshell: if we use custom headers we would need to specify these in the Vary HTTP header, so that proxy caches would know where to find the version number, so that they can compose their cache keys. However, content negotiation using the Vary header is notoriously difficult and often leads to cache fragmentation, which is why it's best avoided.

code of conduct - report abuse