Conflict in response schema, when retrieving collections with paging

[trusanen-solibri]

As discussed briefly in the BCF telecom, there is a slight conflict in the response schema between the BCF API and the OData v4 standard, when retrieving collections.

For example, to retrieve the collection of topics related to a project, the client can issue a request to the /topics-service. The server will then respond with a collection of topics, but the client has no way of knowing, if that collection includes all the topics, or if paging has been applied.

The OData v4 standard includes the odata.nextLink-annotation (link) that can be used to indicate that the response is only a subset of the actual collection and it's value is the location, where the client can retrieve the next subset.

The issue is that the odata.nextLink-annotation is embedded in the response JSON payload as a field, but in the BCF API, we have specified that the endpoint returns a plain list of topics. This creates a conflict with the BCF API schema and the annotation.

To avoid breaking the schema, my suggestion is that we add the odata.nextLink as a response header, which the client could then read and use to retrieve the next subset. If the header is not present, that would mean that all the subsets have been retrieved.

[jasollien]

Could also be specified in Content-Range.
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range

Example: Content-Range: items 200-300/67589

[jasollien]

#230

[GeorgDangl]

This should be resolved along with #187.