Developer Resources

Paging

Pagination is the process of requesting one or more data element sets in order to retrieve all the information associated with a resource.

The pagination parameters used to perform the transitions are captured in a pagination request form which contains the following parameters:

offset : integer

The zero based offset of the next page of data to be presented.

limit : integer

The maximum number of elements to be returned in a page transition.

https://api.paychex.com/companies/99Z5V9BTI8J2FCGESC05/workers?offset=5&limit=5

Pagination parameters are often combined with other form parameters when making a request. For example, when making a filtered request both the filter and page parameters can be simultaneously sent as form parameters. When making collections for requests, it is recommended that you set the content-type of the request to application/x-www-form-urlencoded to convey that page parameters are being transferred. Page parameters can be transferred using either the GET or POST HTTP verbs. When the GET verb is used the page parameters are encoded using URL query parameters. When the POST verb is used the page parameters are encoded in the body of the request. If both of the pagination parameters are not provided on the request then pagination will not be applied (a default paging may be applied in future releases).

 

Hypermedia Controls (Links)

The use of hypermedia controls makes using pagination extremely straight forward. The details associated with the pagination process is captured using hypermedia controls. The standard hypermedia controls associated with pagination are:

next

Provides the link information necessary to transition to the next page of the collection. The next link "rel" is not present if the current page is the last page.

previous

Provides the link information necessary to transition to the previous page of the collection. The previous link "rel" is not present if the current page is the first page.

self

Provides the link information associated with the current page of the collection.

 

Pagination Metadata

The metadata returned in the response will return pagination object that describes information about the current page being presented. The pagination object has the following format:

contentItemCount

The number of elements in the returned content.

pagination

Information about the set that has been returned. itemCount will give you the total number of items that exist.

 

"metadata": {
    "contentItemCount": 5,
    "pagination": {
        "offset": 5,
        "limit": 5,
        "itemCount": 35
    }
}

 

The following formulas may be used to derive page information:

pageNumber

Zero based page number. Use the formula offset / limit rounded as an integer.

numberOfPages

Use the formula ((itemCount- 1) / limit) + 1 

 

Pagination and Cache

In order to paginate the collection over which iterate will remain consistent both in the number and ordering of the elements in the collection. The collection is a snapshot of the state information of a given resource at the time of initial access to insure that the data remains consistent.

When paging the response will contain an ETag and Cache-Control within the header which is that identifier for the collections snapshot. The Cache-Control will specify the max-age indicating how long the cached ETag is valid. To iterate through the pages and keep the collection consistent the ETag needs to be sent into the request's header (note the double quote to comply with RFC 7232)

ETag: "a2dd48cd-c00b-47c5-b59d-8431bd4fc645" 

A pagination request, made in the absence of an entity tag and/or expired ETag, will be treated as a request for a new state representation whose results should be paginated as directed.

 

Pagination Support

The following endpoints have support for pagination:

NOTE: We recommend paging at 100 items per page for clients that have a large amount of workers, if this is not done you run the risk of have long runtimes and timeouts.