Hacker News Reader

Comment by bluetidepro | Hacker News Reader

I like this idea a lot! I'm curious if anyone else finds major flaws in this idea but it seems to make a lot of sense to me. Yes, it may change slightly how you do your calls, but if the logic works and that's the "worse thing" that could come from this then I think it's worth implementing.

View on HN

* You cannot test this from the browser.

* Many, many client developers will be confused by this approach. Also if they're using a shitty http library (often, yes) they'll hate you.

* What happens when someone sends an "Accept: application/json"? If you default to "send the latest" developers will fail to read your docs and get pissed when your next version breaks their code.

* His citation of Fielding's dissertation at best fails to support his claim and at worst is a misunderstanding of it. How is "put this in your accept header" any more of a uniform interface than "this thing goes in urls"? If you're doing HATEOAS[1] properly the answer is: "accept headers are less general and thus worse". If you include api versions as a fundamental part of the notion of a resource they seem to become important enough to need top level (e.g. URI) support.

All in all this seems like a thinly veiled argument for URI purity for its own sake. API versions change the definitions of what a resource looks like and what you can do with it. What more is there to a resource? What benefits, aside from sweeping the versioning mess under the header rug, does this provide?

[1] http://en.wikipedia.org/wiki/HATEOAS

URIs should be black boxes. My understanding is that the client should need no understanding at all of their content.

I agree. This is only possible when all resource access flows from a predefined "root" resource via hyperlinks. If you're doing that, why force (arguably more difficult) accept header handling on your api clients? Then they have to set the accept header correctly at every request instead of getting the version number right once when retrieving the root document. Beyond that debugging now requires access to / a record of the accept headers involved, and returning the latest version for plain application/json creates a very nasty bug for clients.

I don't think REST meaningfully comes down on either side of this idea. I do think practicality sits highly in favor of versions in URIs.

Setting the same Accept header at every request is not difficult or error-prone.

But that aside, what happens when you store versioned resource URLs in the client, and then you want to upgrade your client to a new version of the API? Do you just lose all of your data from the old version, since you don't have a single URL for a resource?

One of the main drawbacks to the HTTP Accept header approach for both versioning and content negotiation is that it makes it less convenient to test from a browser when you can't encode those things in the URL.

Personally I feel that using the header feels more "right" and lines up with the available mechanisms of HTTP. I think the inconvenience could be easily overcome with browser plugins, for example.

You can always add a version=v1 to the query parameters and use that as an override when performing content negotiation. It's still not terribly convenient.

Seems to me he is abusing the Accept-header. In his example, the application provides a JSON-response, but with a vendor-specific media type. Once the API version changes, he changes the media type again.

This is both impractical because if the client application consuming the content happens to be a web browser, it will not see JSON and at least to me seems like a major flaw: if it is JSON, use the appropriate media type.

If you need to fiddle with HTTP headers, probably a X-API-VERSION header would be more logical instead of clobbering the media type.

I don't think "media type" is synonymous with "data format". For example, IANA considers atomcat+xml and atomsvc+xml to be distinct media types [1], despite them both being XML, and there are 406 other XML-based media types in that list.

[1] http://www.iana.org/assignments/media-types/application/inde...

Some libraries that are used to connect to versioned resources like this don't support these types of media types. I tried to version my RESTful APIs exactly like this and ran into integration problems with an externally developed client which was based in Flex. It could have been our contractors not knowing Flex all that well or it could have been inflexibility in the language libraries itself (pun intended).

Reply on news.ycombinator.com