Pagination | Hive Documentations

Delay APIs adopt a pagination strategy similar to GitHub to ensure that API responses are manageable for both servers and clients. For instance, when you make a GET request to /workspaces/delay/members, the API will return a specific subset of results, even if the actual dataset is much larger. This guide explains how to work with paginated responses, how to request additional pages, how to alter the number of items returned per page, and how to script the retrieval of multiple pages of results.

Inspiration Acknowledgment: The design of our API pagination is heavily inspired by GitHub's REST API. We hold immense respect for their contribution to the developer community.

Using link headers

Delay API responses include a link header when paginated. This header will not be present if the specific API endpoint doesn't support pagination or if all results fit into one page. You can inspect the link header either by using curl or by following the respective library's documentation if you are using one. Here's how to do it with curl:

            GET /workspaces/delay/members?page=4 HTTP/1.1
            Host: api.delay.com
            Content-Type: application/json
            Authorization: Bearer $ACCESS_TOKEN
            X-API-Version: $API_VERSION    
        

            curl --include --request GET \
            --url "https://api.delay.com/workspaces/delay/members?page=4" \
            --header "Content-Type: application/json" \
            --header "Authorization: Bearer $ACCESS_TOKEN" \
            --header "X-API-Version: $API_VERSION"
        

A typical paginated response will have a link header similar to this:

link: <https://api.delay.com/workspaces/delay/members?page=3>; rel="prev",
<https://api.delay.com/workspaces/delay/members?page=5>; rel="next",
<https://api.delay.com/workspaces/delay/members?page=50>; rel="last",
<https://api.delay.com/workspaces/delay/members?page=1>; rel="first"

The link header provides URLs for navigating through the dataset:

The URL for the previous page is marked with rel="prev".
The URL for the next page is marked with rel="next".
The URL for the last page is marked with rel="last".
The URL for the first page is marked with rel="first".

You can use these URLs to request additional pages of data:

            GET /workspaces/delay/members?page=50 HTTP/1.1
            Host: api.delay.com
            Content-Type: application/json
            Authorization: Bearer $ACCESS_TOKEN
            X-API-Version: $API_VERSION
        

            curl --include --request GET \
            --url "https://api.delay.com/workspaces/delay/members?page=50" \
            --header "Content-Type: application/json" \
            --header "Authorization: Bearer $ACCESS_TOKEN" \
            --header "X-API-Version: $API_VERSION"
        

Changing the number of items per page

You can adjust the number of items returned per page by using the per_page query parameter:

            GET /workspaces/delay/members?per_page=5 HTTP/1.1
            Host: api.delay.com
            Content-Type: application/json
            Authorization: Bearer $ACCESS_TOKEN
            X-API-Version: $API_VERSION
        

            curl --include --request GET \
            --url "https://api.delay.com/workspaces/delay/members?per_page=5" \
            --header "Content-Type: application/json" \
            --header "Authorization: Bearer $ACCESS_TOKEN" \
            --header "X-API-Version: $API_VERSION"
        

The per_page parameter will be included automatically in the link header, like so:

link: <https://api.delay.com/workspaces/delay/members?per_page=5&page=2>; rel="next", <https://api.delay.com/workspaces/delay/members?per_page=5&page=10>; rel="last"

Last modified: 18 April 2024