Regarding rule #4 (DON'T return arrays as top level responses), I feel that meta information returned about the collection really fits the responsibility of HTTP headers. This is similar to existing response headers like Content-Length and Content-Range. REST clients already work with “out-of-band” information like HTTP statuses and If-Modified-Since. Do we always have add yet another layer to nest meta information in?
I struggle with this concept with RabbitMQ as well. The AMQP 0-9-1 protocol used by RabbitMQ has a headers table at the protocol level for user-defined key-value pairs that can be associated with the message payload. The same question applies here, what should go in this protocol header table vs on the message.
One concern I have about using these user-defined headers is that in my designs I'll typically remove the payload from the AMQP envelope and propogate just the payload to the business logic. What to do if the headers need to be included in the business logic. It seems risky to use the headers at the protocol level.
Assuming that these key-value pairs are not necessarily related to the request semantics (e.g. like `hasMore` in TFA), and also are a unbounded set of potential user-defined key names, then I think it’s appropriate to nest them in the response body. It also sounds like the response is a single message in your case, so the array question doesn’t come up.
You could also place these user-defined headers in a special property of the message, e.g.:
{ // message object
"_headerTable": { … },
// actual message properties here
}
It is a common convention to use underscore-prefixed JSON properties for such meta data.
While you may be right about headers, I think the point the article makes about easily adding more fields to the result without breaking backwards compatibility is pretty compelling.
It’s a good rule for non-collection resources and for the elements of collection resources, but I was specifically thinking about collections, where all top-level information (apart from the elements of the collection themselves) is necessarily meta information about the returned data, and not part of the returned data proper.
