[mstade]

I don’t think you have this right. First, both the URL and the headers are in-band. Out-of-band would be you knowing that the version is v2.3.7, because you just know. In-band is anything in the request and response – headers and all – anything else is an assumption and as such out-of-band.

Moreover, if I understand Roy’s argument correctly, he’s arguing against versioning URLs, because they are meant to be opaque identifiers that doesn’t convey any universal meaning. If you know the second segment of a URL path to be a version, it’s because you have out-of-band knowledge that it is, not because there’s anything in the request to say it is.

If however you have a header that tells what version you wish then that is in-band information that allows you to negotiate the content appropriately with the server. It also means you don’t have to change URLs whenever you make a change to your API, breaking or not. Of course the server and client needs to understand this header (to my knowledge there’s Accept-Version header) and if it’s non-standard then it can be argued that it’s just as bad as versioned URLs. Perhaps, but unless you get very granular with your versions (and most don’t, let’s just be honest) your still at the mercy of what the server chooses to present you at any given time. In fact, REST gives you no guarantees about what you’ll receive at any given point – you may just as well be given a picture of a cat. REST says you should be able to gracefully deal with this. Most clients (that aren’t web browsers or curl) don’t.

[justincormack]

No! Headers are much worse. There is nothing in an API response that tells you in a standard way how to set headers, but there is something that tells you how to follow links (URLs). Accept-version is a non standard header, not defined in the http spec so definitely that is not restful - how do you know if the site supports it or what the version numbers are? You have to hard code in the client!

[mstade]

Arguable. At least an unknown header is likely to just be ignored, whereas a URL that’s changed to update the version will at best cause 404s, unless you keep the old URLs around. If those URLs are still recognized, but routed to the later version anyway then that’s just as bad as using an unrecognized (and likely ignored) header.

In any case, what you’re saying is the point I was trying to make in the latter part of my post. However a typo (or rather, a missing word: “no”) unfortunately changed my meaning entirely. :o(

It should’ve read:

> (to my knowledge there’s no Accept-Version header)

Oops. My apologies for the confusion.

[sitkack]

> I don’t think you have this right.

That is probably true, I don't disagree with anything you are saying. To me the most in-band representation is everything passed in the URL with no user control over headers.

[Whitestrake]

Using "in-band" here doesn't really follow from a technical understanding of the term; the TCP connection is the channel, and anything sent over it (such as an entire HTTP request/response, including headers) is "in-band".

Out-of-band would be a phone call, or perhaps an email - an entirely alternate method of communication.

Transparency to a user (via the client, i.e. browser) isn't really relevant, from a communications standpoint, to whether or not data is considered "out-of-band". Given the subject (APIs), you're not likely to be browsing to these anyway.