Pagination

When dealing with vast amounts of data, returning all results in a single response can be impractical. It can lead to sluggish response times and overwhelm applications attempting to process the entire dataset at once. Pagination addresses this challenge by segmenting large datasets into smaller, more manageable pages.

This approach offers several benefits:

• Improved Performance: Pagination avoids overloading the API server and client applications with massive responses, leading to faster retrieval times and smoother user experiences.
• Enhanced Usability: By presenting results in smaller chunks, users can navigate through extensive datasets more efficiently, focusing on specific pages of interest.
• Reduced Resource Consumption: Pagination minimizes memory usage on both the server and client sides, making it ideal for working with large data volumes.

How Pagination Works

When pagination is implemented for an endpoint, responses will always adhere to a fixed page size of 25 results. To navigate through paginated results, you can leverage the offset attribute within your API requests. This attribute specifies the number of results to skip before starting to retrieve data for the current page. For instance, to retrieve the second page of results (assuming 25 results per page), you would set the offset value to 25 in your request.

Here's an additional indicator to identify endpoints that support pagination: resultsTotal property. Responses will include a property named resultsTotal within the response body. This property reflects the total number of entities matching the request criteria. If the resultsTotal value exceeds the default page size of 25, pagination is available for that specific endpoint and request.

It's important to note that not all API requests will yield paginated responses. Pagination is primarily used for endpoints that return lists of entities, such as search queries or retrieval of collections. Endpoints returning a single entity or specific data points typically won't involve pagination.

Example: Using pagination

curl "https://api.vigil.sh/ato/business-industry-code/find/?query={query}&offset={offset}" \
  -H 'x-api-key: {api-key}'

{
  "results": [
    {
      "id": "382vuw5sc2ZWh13twxvGxrCTSljs29Zuqw==",
      "description": "..."
    },
    {
      "id": "0vTZjyl2c2ZWh13twxvGxorrPSyXOOEyxQ==",
      "description": "..."
    },
    {
      "id": "-KCqpzpAc2ZWh13twxvGxuErh8UZO-C1GA==",
      "description": "..."
    },
    // ...
  ],
  "resultsTotal": 90
}