[comex]

Some of this feels like trying too hard to adhere to HTTP. For example,

> Accept: application/vnd.steveklabnik-v2+json

This declaration loses information, because it no longer contains the MIME type for JSON in a standardized format. Assuming the server responds with the same string for Content-Type, any application that does not know specifically about this API can no longer recognize that it's JSON and, e.g., pretty-print it for a user, as I haven't seen done for JSON but is regularly done for XML by browsers.

On the other hand, the original suggestion:

> Accept: application/json

works in theory, but in practice makes it more difficult to test the API in a browser. This is not the end of the world, but there does not seem to be any real benefit in using Accept. I cannot think of any practical situation where a tool can use the standardized header for an advantage...

[rhu86]

Having your clients send an application specific MIME type can actually be better for browsers as well. All you need to do is provide a representation of your resource in HTML which browsers will request by using "text/html" in the Accept header.

I've found this a nice addition to documentation and, depending on how well the HTML representation has been done, is great for learning/exploring an API.