Consider adding a new collection property to recommend a paging size

[hmassih]

Here are some typical values for the “minimum”, “maximum”, and “default” properties of the “limit parameter":

• minimum: 1
• maximum: 10000
• default: 10

None of these properties can help client implementations that rely on picking a good “limit” for the initial load/display of a collection. These properties affect all collections in an OAFeat service. The default limit of 10 features is too low. Can 3000, 5000, or the maximum of 10,000 be the best paging size that fits all collections? While a paging size of 10,000 works well for a 50,000 point collection, it might not be ideal for a 50,000 polygon collection.

Adding a new property e.g. “RecommendedPagingSize” at the collection level would provide a hint to clients on what could be an ideal paging size for each collection. This removes the guessing factor and makes it the responsibility of the service creator to define this property.

[cportele]

Meeting 2022-01-31: This is a useful proposal, but it requires some experimentation, e.g. in a code sprint. It also isn't something for a corrigendum, so we set the Milestone for v1.1.0.

[richiecarmichael]

@cportele Any chance that this issue could be escalated. Specifically, allow clients to discover a server's (or collection's) paging limit.

Without knowing a collection's paging limit in advance, clients cannot effectively and efficiently request large numbers of items.

At present our web clients attempt to discover the paging limit from the server's open-api page (if any), for example:
open-api > components > parameters > limit > schema > maximum, or
open-api > components > parameters > limitFeatures > schema > maximum

However using the open-api page is far from reliable as schema is inconsistent across implementations. To complicate things further, some implementations define a paging limit on a per-collection basis.

A workaround we are considering is for clients to perform a dummy request for all items. The client would then obtain the limit by parsing the url from the "next" link in the response. This approach is wasteful and certainly not performant. We are eager to know if there is a better alternative or an imminent update to address this.

[cportele]

Meeting 2024-11-18:

• We do not want to duplicate information from the OpenAPI description to the content and we should restrict that to key information that is very useful to clients and hard to parse. These cases pass that test and we will add defaultItemsPageSize and maximumItemsPageSize to the collection information (as recommended information).
• We do not see a good definition of "recommended page size" as this depends on the client and its capabilities (or the network), so it is probably not a good idea to add this.

using the open-api page is far from reliable as schema is inconsistent across implementations

This indicates an approach to parse the OpenAPI definition that is too simple. Maybe we need to add a description how to parse an OpenAPI description to extract information for specific operations.