Pagination

In this guide, we will look at how to work with paginated responses when querying the GroundControl API.

When an API response returns a list of objects, pagination is supported. In paginated responses, objects are nested in a data attribute and have a pagination attribute that provide after and before cursors that you can use as query parameters to browse the next/previous pages of results.

In this example, we requested a page that returned an after cursor with this value: MTIzNGFiY2RlZmdoaWprbG1ubw==. We want to request the next page of results and to do so we use the cursor and put it in the query string of the request.

So, in summary:

Make a request. Results are available as an array in the data attribute. Pagination information is available in a pagination attribute.
The before/after attributes inside the pagination object give you cursors you can put in the URL to make your next request.

Cursors are opaque strings. They are values encoded using base64 but you should not rely on that.

Requesting the first page of results using cURL

curl -G https://api.groundcontrol.sh/projects/YOUR_PROJECT_ID/flags \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginated response

{
  "data": [
    {
      "id": "FC9X3FMI2X8P0Y96BBN46E",
      // ...
    },
    {
      "id": "FY7O25MNQS9VWUTYFN4PV6"
      // ...
    },
    {
      "id": "FCOA24QNYNSATLYXSPM57O"
      // ...
    }
  ],
  "pagination": {
    "before": "YWJjZDEyMzQ1Njc4OTB4eXo=",
    "after": "MTIzNGFiY2RlZmdoaWprbG1ubw=="
  }
}

Requesting the next page of results using cURL

curl -G https://api.groundcontrol.sh/projects/YOUR_PROJECT_ID/flags?after=MTIzNGFiY2RlZmdoaWprbG1ubw== \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginated response

{
  "data": [
    {
      "id": "FRU1WDAWB2RPE2GNN2CVI3",
      // ...
    },
    {
      "id": "FCBD0MWBSO2HIFDSZAI9V6"
      // ...
    },
    {
      "id": "FDTZ5WY81L4E402FXES19N"
      // ...
    }
  ],
  "pagination": {
    "before": "Zm9vYmFyYmF6MTIzNA==",
    "after": "NTQzMmZvb2JhcmJheg=="
  }
}