REST Services Pagination

When returning large collections from a REST service, it is important to ensure that an individual response is not excessive. The standard way of limiting the size of a response to a subset of the large collection is pagination, where not only some of the collection is returned but also information about how to get the next bit of the collection in a future REST request.

Jade supports the paginating of responses when using the JadeRestService class to provide web services, as well as providing a mechanism to easily get the next page when using the JadeRestClient class to consume web services that employ common pagination strategies.

Jade provides the following interface and class for envelope‑based paginating, as well as entities in existing REST service classes. (For details, see Volume 1 of the Encyclopaedia of Classes.)

• JadePaginationEnvelopeIF interface, which is used by the JadeRestResponse class parsePaginationEnvelope method to ensure that an envelope is able to be used by Jade to iterate through the pages of results. When consuming third‑party REST services, you will need to define a class matching its envelope definition, ensuring it implements the JadePaginationEnvelopeIF interface.

• JadePaginationEnvelope class, which is used as the return type for a Jade REST method that would otherwise return a collection in order to provide pagination information such as a link to the next page of results in the HTTP response body. Use the loadCollection method to load the collection you would otherwise return directly into the envelope.

The two main styles of pagination, both of which are supported in Jade both from server‑side and client‑side web services, are as follows.

• With envelope-based pagination, the server returns an envelope object that contains both the paginated results and the pagination information. There is no one standard for the format of this object, but the format for the JadePaginationEnvelope is as follows.

  {
  "data":[{obj1}, {obj2}, {obj3} ...],
  "next": "<link-to-next-page-of-results>"
  }

• With link header pagination, the server returns the paginated results directly in the HTTP response body, with the pagination information (for example, a link to the next page of results) in the HTTP response headers, as defined by:

  https://www.rfc-editor.org/rfc/rfc5988.html#section-5

For more details, see "Client-Side Usage Examples" and "Server-Side Usage Example" in the following subsections.

2022.0.01 and higher