Pagination

The Liquidity Hub API supports offset pagination for operations that return multiple data objects in the response. For example, when you call the GET /quotes, GET /trades, or GET /balances operations with a set of query parameters in the request, the response contains an array of data objects. It also includes the totalPages, first, last, and totalElements fields. If the value of the last field is false, it indicates that there are more data objects to fetch. In that case, you can increment the value of the pageNumber query parameter by 1 in subsequent requests. Continue to make requests until the value of the last field is true, which indicates that you have retrieved all available pages of results.

Tutorial

This tutorial explains how you can use pagination to retrieve all data objects returned by the GET /quotes operation. Pagination in Liquidity Hub APIs
  1. Call the GET /quotes operation and receive a response containing an array of Quote objects.
  2. Examine the value of the last field in the response body.
    • If last = true, you have retrieved all available data objects. No further action is necessary.
    • If last = false, there are more data objects retrieve. Increment the value of the pageNumber query parameter by 1 and call the endpoint again. For more information, see Retrieve subsequent pages of results.

Call the GET /quotes operation

Send a GET request to the /quotes endpoint, for example:
Copy
Copied!
curl -i -X GET \
  '<base_url>/api/v0/quotes?startTime=2021-01-01T01:00:00.000Z&endTime=2021-01-01T01:30:00.000Z&pageSize=3&pageNumber=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
In the above request, you include the startTime and endTime query parameters to specify a time period. The response will contain the list of quotes issued during that time period only. Additionally, you specify the following parameters for pagination:
Query parameterDescription
pageSizeThe number of data objects to return per page. In this case, you request 3 data objects per page.
pageNumberThe sequence number of the page of results to retrieve. As the first page is numbered zero, specify 0 in the first request. Increment this number in subsequent requests to fetch more pages of results.

Examine the response

You receive the following response from the /quotes endpoint:
Copy
Copied!
{
  "quotes": [
    {
      	...
    },
	{
		...
	},
	{
		...
	}
  ],
  "first": true,
  "last": false, 
  "totalElements": 18,
  "totalPages": 6
}
Sorting order

The most recently issued quote is listed first.

The response body represents the first page of results containing three Quote objects that represent quotes issued during the time period specified in the request. The response also contains the following fields that provide pagination information:
ParameterDescription
firstIf true, indicates that the current page of results is the first page.
lastIf false, indicates that there are more pages of results to retrieve. If true, indicates that the current page of results is the last page.
totalElementsThe total number of response objects that match the query parameters you specified.
totalPagesThe total number of pages of response objects. In this case, there are 6 pages of results, starting with page number 0.

Retrieve subsequent pages of results

To make sure you have retrieved all the data objects that match your query parameters, call the GET /quotes operation until last = true - that is until there are no more objects to retrieve. In the above response, the value of the last field is false, indicating that there are more pages of Quote objects to retrieve.
Increment pageNumber by 1
To retrieve subsequent pages of results, increment the pageNumber query parameter value by 1 in your request.
Send another GET request to the /quotes endpoint with the following query parameters:
ParameterValue
startTime2021-01-01T01:00:00.000Z
endTime2021-01-01T01:30:00.000Z
pageSize3
pageNumber1

Request format

Copy
Copied!
curl -i -X GET \
  '<base_url>/api/v0/quotes?startTime=2021-01-01T01:00:00.000Z&endTime=2021-01-01T01:30:00.000Z&pageSize=3&pageNumber=1' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Process the data

Once you retrieve all available data objects, your integration can begin processing the data.

Errors and error handling

The /quotes endpoint may return 400, 404, or 500 error codes. For more information, see Errors.