Link-based pagination

When dealing with large sets of data, receiving results in segments can help apps process information in a more structured way. This retrieval of data, a page at a time, is called pagination.

The /transactions endpoint will standardize on link-based pagination with Akoya API v2.

Consider the following when implementing link-based pagination.

1️⃣ First request

When making an initial transaction call, create the request with the following parameters. The result of that first request will return links to use for paging.

Parameters

These parameters should only be used in constructing the first transaction call. After the first call, requesting pages must be done with links provided in results.

Some data providers may not support offset or limit. Please check the Data Recipient Hub for specific provider documentation for details on pagination support.

offset - The number of items to skip before the first in the response
limit - The maximum number of items to be returned in the response
startTime - ISO 8601 date format in UTC time zone. Example: 2020-03-30T04:00:00Z
endTime - ISO 8601 date format in UTC time zone. Example: 2021-03-30T04:00:00Z

Request

Example


curl --location --request GET 'https://{accessURL}/fdx/v4/{{providerId}}/accounts/{accountId}/transactions?startTime=2020-02-05T01:01:01.005Z&endTime=2022-02-01T23:59:59.001Z' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer xxxxxxxx'

Response

Example with paging

The value of links.next.href may contain the offset, limit, start time, and end time parameters. You should not change these values and use the link as provided.


{
    "links": {
        "next": {
            "href": "/fdx/v4/{{providerId}}/accounts/{{accountId}}/transactions?offset=eyJ0b3RhbEVsZW1lbnRzIjoxNDk3LCJvZmZzZXQiOiIjUF8yMDIxMDMyM18xOTE1MDI5In0=&startTime=2020-02-14T00:00:00Z&endTime=2022-02-09T00:00:00Z"
        }
    },
    "transactions": [ ... ] 
  }

Example without pagination

If all data can be returned without paging, the links.next.href values will be empty. There is no additional data to page through.


{
    "links": {
        "next": {
            "href": ""
        }
    },
    "transactions": [
        {
            "depositTransaction": {
                "accountId": "803af82c25d1093a48d6d43b7bfb3dee",
                "amount": 644,
                "debitCreditMemo": "DEBIT",
                "description": "Online Xfer Transfer to ML",
                "status": "PENDING",
                "transactionTimestamp": "2021-11-02T00:00:00Z",
                "transactionType": "XFER"
            }
        },
        {
            "depositTransaction": {
                "accountId": "803af82c25d1093a48d6d43b7bfb3dee",
                "amount": 50,
                "debitCreditMemo": "DEBIT",
                "description": "Online Xfer Transfer to SV",
                "status": "PENDING",
                "transactionTimestamp": "2021-11-02T00:00:00Z",
                "transactionType": "XFER"
            }
        }
    ]
}

2️⃣ Second request

Use the links.next.href value in the first response payload to construct the next call.

Do not change the link. Changes to offset, startTime, endTime, or limit in the provided link may cause errors or missing data.

For example, in the first response, links.next.href was returned as:


/fdx/v4/{{providerId}}/accounts/{{accountId}}/transactions?offset=eyJ0b3RhbEVsZW1lbnRzIjoxNDk3LCJvZmZzZXQiOiIjUF8yMDIxMDMyM18xOTE1MDI5In0=&startTime=2020-02-14T00:00:00Z&endTime=2022-02-09T00:00:00Z`

To request the next page, use the links.next.href value in the GET request:


curl --location --request GET 'https://{access_url}{{links.next.href}} \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer ABCD'

Example response

Most pagination responses will include links.prev.href. It may be used to page back to previous results. However, a small number of providers do not support prev. Check the Data Recipient Hub for specific provider documentation for details on pagination support. If prev is not supported and your app requires it, store the next links as the user pages.


{
    "links": {
        "next": {
            "href": "example"
        },
        "prev": {
            "href": "example"
        }
    },
    "transactions": [
        {
            "depositTransaction": {
                "accountId": "803af82c25d1093a48d6d43b7bfb3dee",
                "amount": 644,
                "debitCreditMemo": "DEBIT",
                "description": "Online Xfer Transfer to ML",
                "status": "PENDING",
                "transactionTimestamp": "2021-11-02T00:00:00Z",
                "transactionType": "XFER"
            }
        },
        {
            "depositTransaction": {
                "accountId": "803af82c25d1093a48d6d43b7bfb3dee",
                "amount": 50,
                "debitCreditMemo": "DEBIT",
                "description": "Online Xfer Transfer to SV",
                "status": "PENDING",
                "transactionTimestamp": "2021-11-02T00:00:00Z",
                "transactionType": "XFER"
            }
        }
        ...
    ]
}

3️⃣ Ongoing requests

Continue to make requests using the provided links until next is no longer returned in the response.