The Cursored Page pattern adds cursor management affordances to the Page pattern, giving clients cusrsor-style control over the retrieval of the resource’s data.
The Paged resource contains links to the
next element in the cursor. Clients can change the cursor configuration with the Cursor resource. These links have different meaning depending on the type of Paged resource.
In a Data list, the resource presents a list of data points, such as a JSON array. The size of the list in the data page is managed by the
size attribute of the Cursor. Each step via
previous deliver a page of data with
size count of elements. A common example is stock price history.
The Paged resource is a List resource with
list-entry links to Cursor Entry resources. The number of
list-entry links on the Paged resource is managed by the
size attrubute of the Cursor. An example would be search results, where each List Entry represents a resource in the result list. The Cursor Entry’s
cursorMark gives the client the ability to position the cursor at that entry for further navigation. If a mark cannot be provided on the Entry resource then the client will use the Cursor Info’s
cursorMark to reposition the cursor.
In this model, the Paged Resource has no
size concept; each Page is an element in the cursor, like a carousel. The client will step through the cursor by following the
If the Paged resource follows the List pattern, then each list entry is a Cursor Entry resource, containing a
cursorMark field that identifies that element’s position in the list. This value can be passed to the Cursor resource as a
after value to change the cursor position.
Similarly, if the Paged resource presents a data-oriented list of items, like an array of data, those data items should contain a
cursorMark field so the client can change the cursor’s
after point with the Cursor resource.
See the Cursor resource reference for more details on how to change the cursor position and limit.
See the documentation for Paged resource.
The Cursor Info resource describes the cursor configuration used in the Paged resource. This resource has the current
cursorMark and the limit set for the current cursor.
| ||The current page’s |
| ||The item count specified when the cursor was created.|
| ||How many elements present on each page. This property applies to data lists and list resources.|
Points to a Cursor resource that can configure the cursor pagination.
Points to individual Cursor Entry resources in the List. This relationship is required for paged List resources using the Cursored Page pattern. See the List Entry description for more details about this resource profile.
profile: <https://level3.rest/patterns/page/cursor#cursor-entry-resource>, <https://level3.rest/patterns/list#entry-resource>
In a List resource, the cursor entries are individual List Entry resources that contain a field with the entry’s cursor value. This value is used to change the cursor’s position via the Cursor resource. Data lists that use the Cursored Page resource must provide Cursor Entry resources with the
| ||The Entry’s cursor value. Useful for changing the pagination configuration with the Cursor resource.|
The Cursor resource changes the cursor pagination configuration. It is a Lookup resource containing the current configuration. The client can specify a
limit on the number of elements fetched for the cursor and either the
after cursorMark to select a different cursor point to navigate through. They can also set the
size of each page to manage the number of elements to present per page. Once the client submits the lookup, the client redirects to the Paged resource configured with this configuration.
| ||The |
| ||The |
| ||The number of elements to consume for the cursor. If not present in the lookup, the current cursor limit configuration will be used.|
| ||The number of elements to be present on each page.|
If the client only wants to change the page limit, but keep the same cursor position, then they only need to send the
limit field in the lookup. If they wish to change the position of the cursor, they supply either the
after field in the lookup. This
cursorMark value comes from either the Cursor Entry resource or the
cursorMark property of an element in a resource’s list data.
Points to the Paged resource that this Cursor resource configures.
© 2019-2023 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.