Pagination

Many endpoints in HTTP Games return lists of data that could potentially be very large. To keep responses manageable and performant, these endpoints use pagination to break results into smaller, digestible chunks.

How Pagination Works

HTTP Games uses cursor-based pagination, which is more reliable than offset-based pagination for dynamic datasets. Instead of using page numbers, you use cursors that point to specific items in the dataset.

Each paginated response includes:

• total: The total number of items available
• cursorNext: A cursor to fetch the next page of results
• cursorPrevious: A cursor to fetch the previous page of results
• The actual data array (e.g., tiles, dungeons, etc.)

Preparation: Creating a Dungeon

For our examples, we'll use the GridTrap tiles endpoint. First, let's create a dungeon to work with:

curl \
  -X POST \
  -H 'Authorization: Bearer sk_Guei2HJgU...' \
  -H 'Content-Type: application/json' \
  -d '{
    "size": "10x10"
  }' \
  https://api.http-games.almostapps.eu/v1/games/grid-trap/dungeons

This creates a 10x10 dungeon with 100 tiles, perfect for demonstrating pagination. Save the dungeon id from the response for use in the following examples.

Basic Pagination Example

Let's start by fetching the list of tiles:

curl \
  -X GET \
  -H 'Authorization: Bearer sk_Guei2HJgU...' \
  https://api.http-games.almostapps.eu/v1/games/grid-trap/dungeons/[YOUR_DUNGEON_ID]/tiles

The response will look like this:

{
  "total": 100,
  "cursorNext": "after:tile_id_25",
  "cursorPrevious": "before:tile_id_1",
  "tiles": [
    // 25 tiles
  ]
}

Notice that:

• total shows 100 tiles are available in the dungeon
• cursorNext provides a cursor to fetch the next page of tiles
• cursorPrevious provides a cursor to fetch the previous page of tiles, but that would be empty since we are on the first page
• We received 25 tiles (the default limit)

Customizing the Limit

You can control how many items you want per page using the limit parameter. For example, following is how you can fetch only 5 tiles per page:

curl \
  -X GET \
  -H 'Authorization: Bearer sk_Guei2HJgU...' \
  -d 'limit=5' \
  https://api.http-games.almostapps.eu/v1/games/grid-trap/dungeons/[YOUR_DUNGEON_ID]/tiles

Response:

{
  "total": 100,
  "cursorNext": "after:tile_id_5",
  "cursorPrevious": "before:tile_id_1",
  "tiles": [
    // 5 tiles
  ]
}

Forward Navigation

To fetch the next page of results, use the cursorNext value from the previous response as the cursor parameter:

curl \
  -X GET \
  -H 'Authorization: Bearer sk_Guei2HJgU...' \
  -d 'cursor=after:tile_id_25' \
  https://api.http-games.almostapps.eu/v1/games/grid-trap/dungeons/[YOUR_DUNGEON_ID]/tiles

The response will include the second page of tiles:

{
  "total": 100,
  "cursorNext": "after:tile_id_50",
  "cursorPrevious": "before:tile_id_26",
  "tiles": [
    // Next 25 tiles (tiles 26-50)
  ]
}

Backward Navigation

To go back to previous pages, use the cursorPrevious value from your current response:

curl \
  -X GET \
  -H 'Authorization: Bearer sk_Guei2HJgU...' \
  -d 'cursor=before:tile_id_26' \
  https://api.http-games.almostapps.eu/v1/games/grid-trap/dungeons/[YOUR_DUNGEON_ID]/tiles

This will return the first 25 tiles again:

{
  "total": 100,
  "cursorNext": "after:tile_id_25",
  "cursorPrevious": "before:tile_id_1",
  "tiles": [
    // First 25 tiles (tiles 1-25)
  ]
}

Combining Pagination with Filters

Pagination works seamlessly with filtering parameters. For example, to paginate through only the wall tiles:

# Get first page of wall tiles only
curl \
  -X GET \
  -H 'Authorization: Bearer sk_Guei2HJgU...' \
  -d 'type=wall' \
  -d 'limit=5' \
  https://api.http-games.almostapps.eu/v1/games/grid-trap/dungeons/[YOUR_DUNGEON_ID]/tiles

# Get next page of wall tiles using cursor from previous response
curl \
  -X GET \
  -H 'Authorization: Bearer sk_Guei2HJgU...' \
  -d 'type=wall' \
  -d 'limit=5' \
  -d 'cursor=after:wall_tile_id_5' \
  https://api.http-games.almostapps.eu/v1/games/grid-trap/dungeons/[YOUR_DUNGEON_ID]/tiles

End of the Page

When you reach the last page of results:

• cursorNext will be null
• cursorPrevious will still contain a valid cursor to go back
• The number of items returned will be 0

Example of the last page:

{
  "total": 100,
  "cursorNext": null,
  "cursorPrevious": "before:tile_id_76",
  "tiles": []
}

Similarly, when paginating backwards, the last page will have cursorPrevious set to null, the number of items will be 0, and cursorNext will still contain a valid cursor to go in the opposite direction.