Pagination

Some collections might return very large amounts of items. This will usually be the case with /v1/bookings or /v1/events endpoints. To work with these collections we require pagination which will allow you to page through the collection at your own rate.

Using cursor and limit

Collections support the cursor and limit query paramters which allow you to page through a collecttion.

• cursor: An opaque string indicating that there are more pages to read
• limit: An integer indicating the size of each page.

Whenever you query a collection you will receive a JSON object containing the items along with a next field which will contain the cursor for the next page if any.

If the next field is empty, you have reached the end of the collection. This could be because there are fewer items than the limit in the collection or if you have already paged to the end.

If the next field has a value you should repeat the call to the endpoint to get the next page, setting the cursor query parameter to the value of next.

$ curl http://api.understory.io/v1/bookings
{
 "next": "<cursor for the next page>",
 "items": [
    {...},
    {...}
 ]
}

Below is an example of how you could page through all bookings with a Javascript while loop.

let next;
let bookings = [];

while (next) {
  const response = await fetch(
    `https://api.understory.io/v1/bookings?limit=100&cursor=${next}`,
    {
      headers: {
        authorization: `Bearer ${process.env.TOKEN}`,
        'user-agent': 'Understory API Demo',
      },
    }
  );

  if (response.status !== 200) {
    throw new Error(
      `Failed to fetch bookings: ${response.status} ${response.statusText}`
    );
  }

  bookings.push(response.items);

  next = response.next;
}

console.log(`Fetched ${bookings.length} bookings:`, bookings);