Hacker News Reader

Comment by yuchi | Hacker News Reader

I still don't get why we're using the API version in the url. We should use the specialized content-type instead!

Because that approach isn't recommended anymore. In short, it's much harder to for a cache to work effectively based upon Accept & Content-Type headers than it is for it to work on the URL.

For example, here's a quote from Roy Fielding: "In general, I avoid content negotiation without redirects like the plague because of its effect on caching.". In other words, content negotiation for a versioned content-type is OK... if it redirects to a URL that contains the version.

httpbis, the IETF working group in charge of maintaining and developing the core HTTP spec, has deprecated content negotiation: http://trac.tools.ietf.org/wg/httpbis/ticket/81; it's still part of a separate spec (RFC2295), but it's not a core component of HTTP anymore. Why? 'HTTP content negotiation was one of those "nice in theory" protocol additions that, in practice, didn't work out.'

Certainly you can still build an API that works fine using specialized content types. Versions in the URL are a pretty practical approach that work very well too.

Very interesting, thanks. Your link 404s though. Also to you have a link to Fielding's quote?

Google says: http://tech.groups.yahoo.com/group/rest-discuss/message/5857

  > Re: [rest-discuss] Request Header vs. Query String 
  > On 4/11/06, Roy T. Fielding <fielding@...> wrote:
  
  > In general, I avoid content negotiation without redirects like the
  > plague because of its effect on caching.

404 fixed: http://trac.tools.ietf.org/wg/httpbis/trac/ticket/81

Thanks for posting the fixed link; I copied it from another computer, and missed a path. Doh.

Having admittedly not descended very deeply into the rules regarding HTTP caching, why should it be harder to cache based on the cross-section of the URL and the Accept-Header and not simply upon the URL?

I am not certain which method I prefer more honestly, and could fall either way. The comment that it was nice in theory but didn't work in practice seems to more point to not following the spec as it was written then a problem with the spec itself.

I would say it's far more difficult if you want to support the full range of capabilities that the Accept header supports. Accept can support more than a single mime-type, and can also include priorities on each mime-type accepted. If you combine that with multiple clients, I think caching based upon that header would be pretty difficult (or you'd have to make some simplifying assumptions).

Impossible? No, not really.

Worthwhile? My opinion is no. I haven't seen the practical benefits of the content-negotiation approach over the URL approach, but I have seen the practical difficulties, so I'm convinced.

I prefer to have a version identifier at the beginning of all things that may need to be versioning. This should probably extend to URLs. Perhaps you need two or more version schemas: one for changes that affect object names (URLs) and a separate version system for changes that do not (this version sent in the headers).

You could argue that versions of the API are themselves resources and should be discoverable - the Salesforce REST API does this and while I actually prefer the specialized content-type approach myself it certainly does work.

Because it's harder to set the content-type from browsers.

Perhaps if your API won't be that useful to browser based clients, perhaps that'd be the way to go.

> Because it's harder to set the content-type from browsers.

That's only when using HTML forms or links, TFA does not even mention the option of multiple representation of resources so it's irrelevant: there's nothing hard to adding an Accept header to an XHR.

I assume he's talking about developer discovery/exploration.

Versioning the content type is only providing versioning for the response schema; versioning the URL provides versioning for the service as a whole.

Reply on news.ycombinator.com