Pagination only applies to services which return a collection resource, it is needed to enable clients to get a subset of the entire resource, thus avoiding performance and memory issues, while also allowing consumers to decide how many resources of the collection they want to receive.
To enable pagination in one of OverIT APIs, the Page DTO can be used, it is needed to provide an input interface to the client. This interface can be used to specify the desired page and desired number of resources, typically via unexploded query parameters.
The Page object does not allow for endless resource instances in the response, it has a default maximum of 10.000 (ten thousands) instances per call. This default can be customized by a system configurator, changing the value of the company configuration parameters.
There are three standard sizes for pages:
-
Small: 100 instances
-
company.core.rs.pageSize.s
-
-
Medium: 1.000 instances
-
company.core.rs.pageSize.m
-
-
Large: 10.000 instances
-
company.core.rs.pageSize.l
-
This sizing configuration will be available per company, so that every company may have a different sizing on each API.
The page object publishes two parameters for the client to fill: num and size.
Num
This parameter is an Integer that allows the client to specify which page number it wants to retrieve. This parameter is annotated with @NotNull which ensures that once the Page object is specified, at least the num parameter must be specified. The default value is zero, which means that the first page will be retrieved in case the Page object is not specified by the client.
Size
This parameter is an Integer that allows the client to specify the maximum number of entries that a single page is allowed to contain. The default value is zero, which means that a page is allowed to contain any number of entries, effectively disabling the pagination mechanism.
The Page parameter is typically annotated with @NotNull to ensure that the client specifies the pagination object, and with @Valid which ensures that at least the num parameter is specified along with its value. If the client does not respect the Page contract, meaning that it specifies the Page object but not its num attribute, an error 400 Bad Request is generated and returned to the client.