Link

Offset Page Pattern

The Offset Page pattern adds pagination affordances to resources that have multiple elements. The List pattern often applies the Offset Page pattern, giving clients control over pagination of the list’s elements.

The Paged resource has a Page Info resource that describes the pagination configuration. The Paged resource also has cursor links to the previous and next pages as defined in the base Page pattern. Clients can change the pagination configuration with the Pagination resource.

Changing Offset Paging Configuration

The client changes page configuration by POSTing a new configuration to the Pagination resource. This configuration contains the page size and starting page. Pagination responds to the POST by returning the newly-configured Paged resource URL in the Location response header. See the Pagination resource for more information.

Paged Resource

Profile: <https://level3.rest/patterns/page#paged-resource>

See the documentation for Paged resource.

page-info

rel="https://level3.rest/patterns/page/offset#page-info"

Points to a Page Info resource that describes the Paged resource’s pagination configuration.

Page Info Resource

Profile: <https://level3.rest/patterns/page/offset#page-info-resource>

The Page Info resource describes the pagination configuration used in the Paged resource. This resource has relevant state fields describing the current page, page size and other information that helps the client determine which page the related Paged resource represents.

Property Purpose
current The current page. Page numbers are 1-based.
pages The number of pages in the Paged resource. May be unknown, so a client will need to accept text statements in this property.
size The number of elements per page.

Pagination

rel="https://level3.rest/patterns/page/offset#Pagination"

Points to a Pagination resource that can configure the pagination.

Pagination Resource

Profile: <https://level3.rest/patterns/page/offset#pagination-resource>

The Pagination resource is a Form resource that changes the pagination offset configuration. The client can change the page size or the start page so the client can select a different page to view. Once the client submits the form, the response’s Location points to a Paged resource configured with this configuration.

Property Purpose
size The number of elements per page.
start The starting page for the Paged view. Clients use this property to control what page to view. This value is 1-based, and if it is greater than the maximum pages available in the result set then the last page will be set as the start page in the response.

paginates

rel="https://level3.rest/patterns/page/offset#paginates"

Points to the Paged resource that this Pagination resource configures.


Copyright © 2019, 2020 Matt Bishop
Creative Commons Licence
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.