English

简体中文

English

简体中文

Appearance

Pagination ​

The Genstore REST API employs cursor-based pagination for efficient data access. This guide details how to implement cursor pagination for querying data and navigating through pages.

Overview ​

Apps requesting APIs that support pagination will initially receive the first page of data by default. If multiple pages of data are available, the HTTP Response Header will include links to navigate to the next and previous pages.

TIP

  • pageToken is an optional parameter, defaulting to return the first page of data.

  • Requests with pageToken should not include other business parameters except limit. Add additional parameters when querying the first page.

  • The Link in the response header is generated temporarily; it should not be saved for future queries.

Here is an example of how links in the response header might appear:

bash
Link: "< https://{shop}.genmystore/api/{api_version}/customers?pageToken={pageToken}&limit={limit} >; rel=previous, < https://{shop}.genmystore/api/{api_version}/customers?pageToken=opqrstu&limit=3 >; rel=next"

These links utilize the pageToken, limit, and sinceId parameters to manage pagination:

  • pageToken: A pagination cursor that marks the position of a specific page. Defaults to the first page.
  • limit (optional): Define the number of records per page, with a default of 50 and a maximum of 250.
  • sinceId: Start querying from a specific resource ID, primarily used for initiating pagination from a specific position.

Here's how to navigate pagination while querying all orders in a Genstore shop, displaying 10 orders per page:

Retrieve the first page ​

  1. To retrieve the first page of orders, send a request:
bash
GET https://{shop}.genmystore/api/{api_version}/orders?limit=10
  1. The API response for the order list will include the first page of data and a Link field in the response header pointing to the next page:
bash
Link: "<https://{shop}.genmystore/api/{api_version}/orders?pageToken=xNTM4OTA4Mjk1MjExMTI...&limit=10 >; rel=next"

Retrieve the next page ​

  1. Extract the Link value from the response header and use the rel='next' link to fetch the next page:
bash
GET https://{shop}.genmystore/api/{api_version}/orders?pageToken=xNTM4OTA4Mjk1MjExMTI...&limit=10
  1. The response will continue to provide links for both the previous and next pages:
bash
Link: "< https://{shop}.genmystore/api/{api_version}/orders?pageToken= eyJzaW5jZUlkIjoiMTYwNTc2NjAxN...&limit=10 >; rel=previous, < https://{shop}.genmystore/api/{api_version}/orders?pageToken=ODgiLCJkaXJlY3Rpb24iOiJu...&limit=10 >; rel=next"

Retrieve the previous page ​

  1. Use the rel='previous' link from the response header to go back to the previous page:
bash
GET https://{shop}.genmystore/api/{api_version}/orders?pageToken= eyJzaW5jZUlkIjoiMTYwNTc2NjAxN...&limit=10
  1. You will receive the data for the previous page as indicated.

Query from a specific position ​

To start querying from a specific orderId, e.g., orderId 10000, with 10 records per page:

  1. Structure the REST API request as follows:
bash
GET https://{shop}.genmystore/api/{api_version}/orders?pageToken=xNTM4OTA4Mjk1MjExMTI...&limit=10&sinceId=10000
  1. The response will be similar, beginning the query from orderId 10000.