perPage limit - How to inform the client about the maximum value

[joelvogt]

• Pagination limit of 200 described in documentation, not available as headers or query parameters: https://sensedia.com/en/uncategorized/api-pagination-and-filters/
• Pagination limit 100, not available as headers or query parameters: https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/paginate

I suggest we also describe per Page limit in the documentation (openapi spec and standard document), but not as extra header information

[CraigRe]

Documentation needs to explain that it is events per page; in the context of events, WG still needs to decide what this means for master data.

With respect to EPCIS Documents, does pagination refer to the number of EVENTS? With respect to EPCIS Master Data documents, does pagination refer to number of VOCABULARY ELEMENTS ?

For all endpoints, will add guidance on maximum length of content per page; Server can indicate max length per page (e.g., x bytes). Add non-normative language on the need to exercise common sense in order to lighten payloads when (i.e,, before) populating EPCIS documents with large amounts of binary data (e.g., imagery), which could instead be referenced via URL.

[joelvogt]

I updated the perPage documentation:

    This parameter helps to control the amount of data returned to the client through pagination.
    In the case of EPCIS events, `perPage` specifies the maximum number of events in a response to the client . 
    In the case of EPCIS master data, `perPage` specifies the maximum number vocabulary elements. `perPage`
    specifies the upper limit of resources in a response body. It does not mandate that the server reaches this
    limit. For example, if the server sees that some EPCIS events are very
    large, the server can decide to return fewer events to avoid creating an error because the response body is too
    large.

    As long as there are more resources to retrieve, the Link header contains the URL of the next page and
    the attribute `'rel="next"'`. The last page is indicated by the absence of the `'rel="next"'`. Depending on the
    implementation, there can be a global upper limit for the `perPage` value that the client cannot overwrite,
    which should be stated in the documentation.