Pagination

When working with collections of data in the Artos Store API, you'll often need to handle responses that contain many items. Our API implements pagination to break these responses into manageable chunks, making your applications more efficient and responsive.

How Pagination Works

The Artos Store API uses page-based pagination to organize large sets of data. By default, responses are limited to 20 items per page, but this can be adjusted using query parameters.

Every paginated response includes two important sections:

A meta object that provides information about the pagination state
A links object that provides pre-constructed URLs for navigation between pages

The Meta Object

The meta object contains all the information you need to understand the current pagination state:

Name
itemsPerPage
Type
integer
Description
Number of items included in each page (default is 20)
Name
totalItems
Type
integer
Description
Total number of items available across all pages
Name
currentPage
Type
integer
Description
The current page number being returned
Name
totalPages
Type
integer
Description
Total number of pages available based on the current page size

The Links Object

The links object provides pre-built URLs that you can use to navigate through the pages:

Name
current
Type
string
Description
URL for the current page
Name
next
Type
string
Description
URL for the next page (only included if a next page exists)
Name
previous
Type
string
Description
URL for the previous page (only included if not on the first page)

Example Response

Here's an example of a paginated response from the Products API endpoint:

This example shows a response where:

There are 43 total products
We're viewing page 1
Each page contains 20 items
There are 3 total pages
A link to the next page is provided

Using this information, your application can implement pagination controls and efficiently navigate through the available data.

Paginated response structure

{
  "data": [
    // Array of product objects
    // 20 items in this example
  ],
  "meta": {
    "itemsPerPage": 20,
    "totalItems": 43,
    "currentPage": 1,
    "totalPages": 3
  },
  "links": {
    "current": "?page=1&limit=20",
    "next": "?page=2&limit=20"
  }
}

Pagination Parameters

When making API requests to endpoints that return collections, you can use the following query parameters to control pagination:

Name
page
Type
integer
Description
The page number to retrieve (defaults to 1)
Name
limit
Type
integer
Description
The number of items per page (defaults to 20, maximum 100)

Example Request

GET

/store/products

curl "https://api.artosapp.com/store/products?page=2&limit=15" \
  -H "x-store-id: {your-store-id}"

Best Practices

When implementing pagination with the Artos Store API, consider the following best practices:

Use the links object: Rather than constructing pagination URLs manually, use the pre-built URLs provided in the links object.
Respect default limits: While you can increase the limit parameter, keep it reasonable (under 100) to ensure optimal API performance.
Display pagination information: Use the metadata to show users information like "Page 1 of 3" or "Showing 20 of 43 items".
Handle empty pages gracefully: If a user navigates to a page that doesn't exist, your application should handle this elegantly.

Store Access Error Handling