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 thelimit
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
andpreviousPage
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.