Fred is a software jack of all trades, having worked over the last 24 years at every stage of the SDLC and has authored [two books](https://www.amazon.co.uk/Fred-Heath/e/B08F3Q1H1M).
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:
*api.example.com/v1/*
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.
Fred is a software jack of all trades, having worked over the last 24 years at every stage of the SDLC and has authored [two books](https://www.amazon.co.uk/Fred-Heath/e/B08F3Q1H1M).
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. bizcoder.com/the-insanity-of-the-v...
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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:
Caching becomes difficult, so for that reason I reject this.
Adding to the HTTP Accept header
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
VaryHTTP 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. bizcoder.com/the-insanity-of-the-v...