Hi Jonathan, good post, this is a rarely-examined issue when creating REST APIs. My view is:
This approach isn't RESTful as we are having multiple URNs for the same resource, which breaks REST constraints for resources
Caching becomes difficult, so for that reason I reject this.
*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. bizcoder.com/the-insanity-of-the-v...
We're a place where coders share, stay up-to-date and grow their careers.
We strive for transparency and don't collect excess data.