GET for Collection endpoints vs Document endpoints return inconsistent Item content

[hluz]

• Individual items returned from a GET on a Collection endpoint do not include "parent" and "collection" links. For consistency with a GET on Document, it should.
• Item returned from a GET on a Document endpoint does not include "etag" value. Although an Etag header is included in the response, for consistency with a GET on Collection, it should also be included in the Content item.

[nicolaiarocci]

Hello and thank you for your comments. Both are actually design decisions taken to minimize payload size, which is an important factor when dealing with possibly unpredictable connections (think mobile).

If you're on a collection endpoint, by definition you already know the documents parent (you're on it). Besides, that piece of information is actually in the payload already (the "self" link in _items). Repeating that link for every document in the payload seems like an optimization waste. Consider that there could be hundreds (or even thousands) duplicates in case the API maintainer, for some obscure reason, decides to turn pagination off.

For the same reason the etag is not duplicated at the item endpoint. It's in the header already, you don't probably need that piece of information twice within the same payload. At collection endpoint we're forced to serve individual etags since we want to allow for subsequent direct conditional requests (If-Match) on individual documents, without forcing a previous document lookup. For coherence however, it would probably be reasonable to add the etag in the json/xml stream too, as in this case the 'waste' would be pretty much insignificant. Let's see what/if others have something to say on this point.

[hluz]

Nicola, I understand and see the validity of your point about minimising payload size, and about the duplicated data inside the payload. For the etag though, as you mention, it would make sense to be in the payload (as well the HTTP header). In other words, forget about point 1 and keep point 2.

[nicolaiarocci]

What if this 'choerence mode' is disabled by default but you can switch it on with a global setting, something like a COHERENCE_MODE boolean?

[hluz]

That would totally do it, of course ;-)

[nicolaiarocci]

Screw the COHERENCE_MODE we'll just throw the ETag in the payload instead. :)