Hacker News Reader

Comment by bryanh | Hacker News Reader

The whole point of a REST API version bump is that it is an artifact of introducing necessary breaking changes (either removing an endpoint at X path, removing Y keys, or even serializing dates in Z format).

Though there have been many detractors, I still think URL based versioning is the best way to go. How do you version a header on a resource that goes away or pops into existence? What if I just ask for "application/json" or the "freshest" due to ignorance and you move the target and get even fresher? There is very little practical benefit to versioning in a HTTP header except some argument about URI purity.

View on HN

I feel it best to supplement your REST API with a pure-URI scheme available on _all_ of your resources that is dependent on the request type. You might have both;

https://api.test.com/v1/resource -- standardized API response https://test.com/resource -- "pure" object if JSON is requested, pretty HTML-wrapped version if not.

You can rely on the versioned API to have a specific format and metadata (things like number of results, query times, etc), while the "pure" version is just a raw JSON object.

If you're writing a client which is sensitive to the resource representation changing over time and you're using something that calls itself an API, hopefully one would skim the provided docs enough to see that you might want to explicitly state the version you want. Or notice that the Content-Type returned for the generic application/json query is a versioned type.

I acknowledge that it's a little more work than just banging out a versioned URI, but it's not that much work and I like the URI/conceptual purity.

> and I like the URI/conceptual purity.

This sums up pretty much the whole debate. Pragmatics vs idealists.

The interesting thing is that it is a false dichotomy - it's easy enough to implement both. Perhaps enhanced by adding a flag on the documentation to flip between pragmatist/idealist so each only sees their one way to do it right...

Another solution that I've seen is to use a custom header in the request such as X-Api-Client-Version: 1

If the header isn't provided, then the most current version of the API is called. The nice thing about this is that it doesn't 'pollute' the URI and it allows for automatic upgrading to the latest version of the API if the developer doesn't specify the API version.

Silently and automatically upgrading an API is a horrible idea.

It depends on how your API is designed. If it's a tightly coupled RPC-style API or something, this is obviously a bad idea because you'll break every client that didn't see the change coming. But the goal of designing APIs in a hypermedia style is to eliminate this tight coupling and include in each response all the information that a client would need to traverse the application's states. When this is designed properly, it is easier to change the API's functionality without breaking existing clients.

The web is a great example of this (although you may have to squint a bit to see it). Browsers don't need to add additional code or install plugins to handle forms with different fields or links to content of different types, because the semantics of those elements and their interactions are well-defined.

If you're requesting a sub-resource without navigating to it from a known, fixed root, you're not doing HATEOAS. If you're not doing HATEOAS, then that's level 2 REST. The upshot is that you have to have stable URIs, and therefore you have to version them. If you make the extra effort, you get complete freedom to rework your URI schema at any time.

Reply on news.ycombinator.com