The Seelab API supports pagination for endpoints that return large collections of data. Pagination helps manage large datasets by splitting them into smaller, more digestible pages. This way, you can efficiently access your data without overwhelming your application or the server.

Understand Pagination Parameters

When you make a request to an endpoint that supports pagination, you can control how the data is returned using the following query parameters.

Parameter	Description	Example
page	Specifies which page of data to retrieve. By default, it's set to `1`. If you want the third page, set `page=3`.	page=3
limit	Specifies how many items to include per page. Maximum value is `100`. For example, `limit=20` returns 20 items per page.	limit=20

Example Request:

GET /resources?page=3&limit=20

This request retrieves the third page of results, with 20 items per page.

Interpret the Pagination Response

When you receive the response, it will contain information that allows you to understand the pagination status. Here are the key parts of a paginated response.

Parameter	Type	Description	Example
currentPage	`integer`	Tells you which page of data you are currently viewing.	1
previousPage	`int\|null`	Shows the number of the previous page, or `null` if there are no previous pages.	null or 2
nextPage	`int\|null`	Shows the number of the next page, or `null` if there are no more pages available.	null or 2
items	`array<object>`	Contains the list of items returned on the current page.

Example Response:

{
  "currentPage": 3,
  "previousPage": 2,
  "nextPage": 4,
  "items": [
    { "id": 1, "name": "Item 1" },
    { "id": 2, "name": "Item 2" }
  ]
}

In this example, you are on page 3, with page 2 as the previous one and page 4 as the next available page. The items array contains the content for the current page.

Handling Errors When Navigating Pages

Sometimes you may request a page that doesn't exist—perhaps you've reached beyond the available data. When this happens, the API will return an error with a 409 CONFLICT status.

Example Error Response:

{
  "error": 1000,
  "message": "Requested page does not exist",
  "data": []
}

To avoid this, make sure to use the nextPage and previousPage metadata to keep track of available pages.

Best Practices for Using Pagination

Here are some tips to make the most out of pagination:

Set a Suitable limit: Adjust the limit parameter based on your needs. Smaller limits give faster responses, but you may need to make more requests. Larger limits can help reduce the number of requests but may slow down individual responses.
Use Pagination Metadata: Always check nextPage and previousPage in the response to navigate through pages effectively. This helps ensure you don’t request a page that doesn’t exist.
Avoid Hardcoding Page Numbers: Instead of assuming the number of pages, use the nextPage value from the response. This ensures that your application can dynamically handle changes in data size.