Skip to content

DEVDOCS-6327 - Add cursor pagination #944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

DEVDOCS-6327 - Add cursor pagination #944

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/start/best-practices/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,37 @@ The [BigCommerce Ruby API client](https://github.com/bigcommerce/bigcommerce-api

Looking for more information on handling requests? Continue with [API rate limits](/docs/start/best-practices/api-rate-limits) to learn about our best practices.

## Use cursor-based pagination whenever possible

For larger data sets, pagination is necessary to read through all the information being retrieved. Generally, the BigCommerce API provides this functionality through an `offset` structure, but some endpoints include a `cursor` structure either in addition to, or in lieu of, the `offset` structure.

While you may use either `offset` or `cursor` pagination wherever they exist, `cursor` pagination is both more efficient and less computationally complex. As such, `cursor` pagination is the recommended method.

### Cursor pagination

Wherever available, `cursor` pagination is used by providing a limit with a request using either a `first`, `last`, or explicit `limit` directive. If a `cursor` is also provided with the request, it will serve as the starting point for data retrieval.

In order to achieve full pagination, the ending `cursor` of returned data also includes a flag indicating whether another page of data exists.

An example workflow for `cursor` pagination is outlined below:

1. Make a request with a set `limit`.
2. Check if there is another page, and make another request on the `endCursor` associated with the response.
3. Repeat step 2. until no further pages exist after the `endCursor`.

For explicit examples of `cursor` pagination, refer to [GraphQL Storefront API - Pagination](/docs/storefront/graphql#pagination).

### Offset pagination

By contrast with `cursor` pagination, `offset` pagination takes a `limit` and a starting `offset`, which must be compared against the totality of data being retrieved. This increases computational complexity by requiring extra comparisons and computations before moving to the next request.

An example workflow for `offset` pagination is outlined below:

1. Make a request with a set `limit` of returned data and an `offset` of `0`.
2. When the response is returned, verify whether another request is required.
3. If necessary, make another request with the same `limit` and `offset` increased by the value of `limit`.
4. Repeat steps 2. and 3. until no further requests are required.

## Resources

### API platform
Expand Down Expand Up @@ -84,6 +115,7 @@ When building a headless storefront, it's best practice to group related request
* [REST Storefront Cart API](/docs/rest-storefront/carts)
* [Upsert price list records](/docs/rest-management/price-lists/price-lists-records#upsert-price-list-records)
* [BigCommerce Ruby API client (GitHub)](https://github.com/bigcommerce/bigcommerce-api-ruby)
* [Offset and Cursor Pagination explained](https://dev.to/jackmarchant/offset-and-cursor-pagination-explained-b89)

### External articles

Expand Down