The standard approach to expressing errors in a REST API
is to use HTTP status codes. As is often the case with
REST, this works fine for simple systems, but is simply
too limiting for more sophisticated systems, particularly
those which might submit a JSON or XML document to
describe a POST request.
That's what the response body is for. If a client PUTs (or POSTs) a malformed representation, it's reasonable for the response to be 400 with error detail in the body.
The "depth" parameter is kind of interesting, since it gives the client a choice as to whether multiple resources are included in the response. I'd be interested to see how others implement this (or if the client is given no choice at all).
But essentially this is a straightforward choice between latency and response size.
It definitely makes sense to have it in the query string, and I think people are already doing it that way, but the author makes a good point - it isn't a resource in its own right, it's merely a different representation. But in my experience, requiring Accept manipulation outside of .json versus .xml makes your service less usable by clients, which often don't expose anything besides the url.
I think both interpretations can be defended. Though if you're playing with the Accept: header it's important to correctly set Vary: as well.
> But in my experience, requiring Accept manipulation outside of .json versus .xml makes your service less usable by clients, which often don't expose anything besides the url.
Browsers have that limitation (and numerous others), but if a programmatic HTTP library does not expose this, you need to throw it out. The Accept header is not part of the "immutable" headers of XHR either.
The "depth" parameter is kind of interesting, since it gives the client a choice as to whether multiple resources are included in the response. I'd be interested to see how others implement this (or if the client is given no choice at all).
But essentially this is a straightforward choice between latency and response size.