gistfile1.txt

in response to http://twitter.com/#!/sj26/status/179435393622605825 - Namely, did I consider using Headers on the response.

Now, I didn't consider them in depth but I did consider them a little. Most of the reasons to use them were pragmatic in nature
(following a possibly flawed thought pattern):

- I felt that those details about the data are part of the data itself - versus extra metadata about the resource in general.
- Collections still ideally to be under an object (versus an array) for security reasons - http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
- In doing so, it makes sense that if you're going to put the data inside a nested object, ideally you should place the data there as well for consistency.
- It makes the style of clients slightly easier because JSON conveys type information not necessarily present in headers.
- Unicorns.

With all of that said and done, one of the items on the cards for rocket pants is the ability to flip that around - Basically, the idea of presenters in the regards they handle setting the metadata on the request. The usefulness then being it's easier to do things like https://en.wikipedia.org/wiki/HATEOAS without having to manually override stuff. Likewise, things like switching the way versioning is handled should be optionated but easy to switch out if you disagree.

You should've used markdown. :P

I disagree with your first point: those details are metadata about the actual data you are shipping, i.e. this data is only 10 of 20 records, the rest can be accessed from http://.../data/rest, etc. The data itself is the records you want to work with. It's similar to Content-Length, Content-Type, ETag, etc—they describe the data and it's place. The Link header feels designed for pagination, and html <link> tags are a crux for these the same as <meta http-equiv>.

If I want to see that data in json, xml, and potentially other more opaque formats—like pdf, xls, a binary, etc.—I should be able to access that metadata in the same fashion. I'm thinking of the github-like way to access a pull request, a patch and a diff from the same location and different extensions/accept headers. APIs should respect Accept also.

Also, I expect the response body to vary by status code. For a 422, I expect the response to be the list of errors. For a 404, I expect an explanation. For a 200, I expect the response I want. For a 204/205 I expect nothing. Again, these responses may require additional metadata which could only belong in the headers.

Collections can still be under an object, i.e. {things: [{id: 1}, {id: 2}]}. I don't believe metadata which might change independent of this data should be coupled to it.

I think type coercion is a non-issue. All HTTP headers have an implied type.

Another good argument Greg just proposed, putting metadata in the headers means you can HEAD for the metadata, potentially just the pagination links to skip around the result set without downloading everything.

I think I'd argue that it goes against discoverability, but the benefits I think are def. worth making it one of the default options. I'll have a look into it. I'm also planning on taking some of the design ideas from Designing Hypermedia APIs into consideration for the next major release.