Pagination

In this guide, we will look at how to work with paginated responses when querying the Swypex Partner API. By default, all responses limit results to 10 items. The API uses cursor-based pagination for efficient navigation through large result sets.

When an API response returns a list of objects, pagination is supported. In paginated responses, objects are nested in a resource-specific attribute (e.g., cards) and include a nextCursor attribute when more results are available.

Cursor-based pagination

The Swypex Partner API uses cursor-based pagination, which is more efficient and reliable than offset-based pagination. Instead of page numbers, you use an opaque cursor token to fetch the next page of results.

How it works

Make an initial request with an optional limit parameter
The response includes a nextCursor field if more results are available
Use the nextCursor value in your next request to fetch the next page
Continue until nextCursor is absent or null

Query parameters

Name
cursor
Type
string
Description
Pagination cursor for continued iteration. Use the nextCursor value from the previous response to fetch the next page.
Name
limit
Type
integer
Description
Limit the number of items returned per page. Default is 10.

Initial request

curl -G https://p.swypex.com/v1/card \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response with next cursor

{
  "cards": [
    {
      "id": "CRD1000000000",
      "last4": "1234",
      "nickname": "Business Travel Card",
      "cardHolder": {
        "id": "USR1000000000",
        "fullName": "Sara Amr"
      },
      "limits": {
        "daily": 500000,
        "monthly": 2000000,
        "atm": 400000,
        "approval_based": null
      }
    }
    // ... 9 more cards
  ],
  "nextCursor": "eyJpZCI6IkNSRDEwMDAwMDAwMDkifQ=="
}

Fetching the next page

To fetch the next page, include the cursor parameter with the value from nextCursor in the previous response.

When you've reached the last page, the nextCursor field will be absent from the response.

Fetch next page

curl -G https://p.swypex.com/v1/card \
  -H "Authorization: Bearer {token}" \
  -d cursor="eyJpZCI6IkNSRDEwMDAwMDAwMDkifQ==" \
  -d limit=10

Last page response (no nextCursor)

{
  "cards": [
    {
      "id": "CRD1000000010",
      "last4": "5678",
      "nickname": "Marketing Expenses",
      "cardHolder": {
        "id": "USR1000000010",
        "fullName": "Ahmed Hassan"
      },
      "limits": {
        "daily": 1000000,
        "monthly": 5000000,
        "atm": 0,
        "approval_based": null
      }
    }
    // ... 2 more cards (only 3 remaining)
  ]
}

Suggested Best practices

Cursors are opaque tokens and should not be parsed or constructed manually. Always use the exact value returned by the API.

Don't parse cursors: Cursors are opaque strings. Don't try to decode or manipulate them.
Don't store cursors long-term: Cursors may expire or become invalid. Only use them for iterating through a result set.
Handle missing nextCursor: When nextCursor is absent, you've reached the end of the results.
Use appropriate limits: Choose a limit value that balances performance and response size for your use case.

Example: Iterating through all cards

Here's an example of how to iterate through all cards using cursor-based pagination:

Card Pagination Example

import ApiClient from '@swypex/partner-api'

const client = new ApiClient(token)
let cursor = null
let allCards = []

do {
  const response = await client.cards.list({
    cursor,
    limit: 50
  })

  allCards = allCards.concat(response.cards)
  cursor = response.nextCursor
} while (cursor)

console.log(`Fetched ${allCards.length} cards`)