Update README to explain `top` in pagination response

[GeorgDangl]

BCF-API/swagger.yaml

Line 1758 in 19ac4f4

top:

The top property describes how many items are at most returned per request / per page. If a server responds with a lower top value than what the client originally asked for, then that means the server has imposed a lower limit than what was requested.

If no page size is requested, the server will still populate the top property with it's default limit.

Maybe this part should be included in the Foundation API?

[ChernyshevDS]

Could you please explain the reason behind adding these fields in the first place? If a client makes a request, he already knows the values he passed to the endpoint, and I don't think there is a situation when they can change. As for limiting the page size by the server, don't you think that returning an error is a more clear approach? If I've requested a 1000 items, and server allows 10, I think that's my error, and it's better to fix it than try to write some logic to dynamically change the page size based on server response.

Another one is nextLink - I can understand the reason for this field when using keyset- or cursor-based pagination, but we are using OData-based API, which implies offset-based approach, so generating a next page link is a trivial task, and it's not worth it in my opinion to add this field into the response.

If I miss something, I'll be glad to hear that I'm wrong. Best regards.

[GeorgDangl]

The reason to include the top parameter back in the response is so that the server may easily communicate its limit back to the client. For example, you're requesting the top 1000 items, but the server only allows 10 - so you'll get a response with top=10 back.

Since we have different servers, we possibly have different limits in practice and communicating this back serves a purpose.
If we would e.g. just return an error, then we either need to create a specific error format to return the max allowed value or let the clients send requests until they've found a value that is accepted by the server.

[GeorgDangl]

I've started a PR here: #386