Skip to main content

Pagination

Introduction​

Pagination is a technique used to break large datasets into smaller, manageable chunks. Some of the Lightspeed Restaurant K-Series APIs offer pagination, allowing integrators to retrieve data incrementally instead of all at once. Different APIs implement pagination in different ways, but the fundamental principles remain the same.

Pagination Methods​

Below are the types of pagination methods used in Lightspeed Restaurant APIs.

Page-Based Pagination​

Used in the Rich Item API, the Staff API, and the Reservation Platform API, page-based pagination retrieves data in predefined chunks, typically controlled by page and size parameters. The page parameter specifies the page number, while size determines how many records are returned per request.

Example

GET /i/richItem/{businessId}?page=0&size=10

GET /staff/v1/businessLocations/{businessLocationId}/shift?page=1&size=10
  • Retrieves the first page with 10 records per page.
NOTE

Starting page values vary by API.

Offset-Based Pagination​

Used in the Items API, offset-based pagination allows requests that specify a starting point (offset) and the number of results amount.

Example

GET /items/v1/items?businessLocationId={businessLocationId}?offset=20&amount=10
  • Skips the first 20 records and returns the next 10
  • Default values typically start at offset=0

Cursor-Based Pagination​

In the Financial API, as well as Financial API V2 the initial request returns a set of results, determined by pageSize, and a parameter called nextPageToken is used for each subsequent request to indicate the starting point of the next set of results.

Example

GET /f/v2/business-location/{businessLocationId}/sales?from=2024-09-06T01:00Z&to=2024-09-06T23:00Z&pageSize=25

GET /f/v2/business-location/{businessLocationId}/sales?from=2024-09-06T01:00Z&to=2024-09-06T23:00Z&pageSize=25&nextPageToken=MjAyMy0wOS0wNlQyMDo0MTozOS45Njla
  • The first request retrieves the first 25 records of the dataset.
  • The subsequent request uses the token returned in the previous request to retrieve the next 25 records from the specified time range.

Handling Pagination​

To paginate through an API's data programmatically, you'll typically follow a loop pattern that makes repeated requests to the endpoint, adjusting pagination parameters with each iteration. Here's a breakdown of how this works:

1. Select the appropriate set of pagination parameters​

  • page and size
  • offset and amount
  • pageSize and nextPageToken

2. Start with Default Values​

  • Initialize your request with starting values (e.g., page=0 or offset=0).
  • You may also want to define the size of the page (e.g., size=100, amount=100, pageSize=100)

3. Make the First Request​

  • Use these parameters to fetch the first set of results. Parse the response and store the returned data.

4. Check for More Data​

  • If the API provides a total_pages or total_count value, compare it to the current page or offset.

  • If there’s no explicit count, you can infer the end of data when the number of returned records is less than the requested size.

  • For cursor-based pagination, look for a nextPageToken or similar value and use it in the next request.

5. Repeat Until Done​

  • Continue making requests and collecting data until you’ve retrieved all pages. Stop when there are no more results or when you’ve hit the last page.

6. Handle Errors Gracefully​

  • Always check HTTP status codes and add retry logic if necessary, especially for network or server errors.