Add note about pagination

[jasollien]

No description provided.

[ykulbak]

@jasollien is it common to specify odata.totalCount and odata.nextLink in a header (and not the json payload)? Is this a workaround to avoid a backward incompatible change to the payload?

[Amoki]

I've seen many API using headers to add some context to the query (not with odata though).
It may be less convenient sometimes but changing the body response is a hard task.

A dot in a header name seems to be forbidden (https://tools.ietf.org/html/rfc7230#section-3.2.6)

[GeorgDangl]

I'm also not a huge fan of using headers to transport data myself, since it makes client implementations harder. So maybe we should keep the headers optional?

Also I think we should prepend the headers with a x- to indicate that they're custom headers.

[Amoki]

x- for custom header has been deprecated (https://tools.ietf.org/html/rfc6648 and https://stackoverflow.com/a/3561399). I think a prefix to avoid any name conflict could be great

[pasi-paasiala]

Please provide a bit more information in the commit message. Is this related to some issue? Content of the change seems fine.

[GeorgDangl]

This is a pretty old PR, but still an important one😀

We've just discussed this in the call, and it looks like there's more work to do. The basic facts right now are:

• When we return paginated results / list results, we're directly returning an array like [...] of items from the BCF API
• OData (and most other implementations, too) seem to assume that when you return a list, you wrap it in a response object like { "values": [...] }
• Wrapping gives you flexibility, e.g. you can add additional properties like a totalCount, currentPage or similar to the response
• The current version of OData does not seem to use the headers as suggested in this PR, but only relies on custom properties, e.g. @odata.totalCount in the wrapping model

-> We need to spend a bit of time on that issue. In the discussion, we felt that we probably have to modify all the responses for list results to return wrapping elements, but this is a bit of work.