18F API Standards

Secondly, because you don't need to parse a JSON response to make decisions based on the response, both clients and servers can potentially be simpler and faster. If you got a 206 response and 1000 items back, but you made the request without an accept range header, not knowing if you were going to receive 10 items or 10000 items, you don't need to parse the JSON to find this out. This is opposed to just retrieving a 200 response, parsing and processing 1000 items, getting to the end to find a "next" property in your JSON you weren't expecting, and then firing off another request, when you could have already queued a second request if you had read the header first before processing your response. (RFC2616 Section 3.12 gives you some leverage in specifying range units, so its easy to define the range in items instead of bytes.)

However, I don't think that creating new headers is a good idea. My recommendation is simple: If it's in the HTTP spec and you are can use it according to how it's defined (like my items range example), then you should use it. If it's not in the spec, just go ahead and put it in the URI/response. The exceptions to that is maybe custom authentication mechanisms (i.e. HMAC or cookie based authentication), or anything which may be performance sensitive. For example, I have endpoints that are used in browser and by batch machines. It's easy to just use cookies for the browser and HMAC for batch machines.