Sorting and pagination

How do you sort and paginate responses to an API request.

Response results can sometimes have a lot of content—far more than you’d want to see in a single request. For example, a GET request to the /customers endpoint with no query parameters results in every customer being returned which may number in the tens of thousands. Depending on the specific endpoint that returns an array of resources, we provide query parameters so that you can:

  • Limit the number of results returned.
  • Sort the results (for example, alphabetically).
  • Paginate the results.
  • Return a specific range of results.

Sorting response results

Some APIs provide the ability to sort the results that are returned from a URL query. If you omit a sorting parameter, the results returned are shown in a default order which depends on the API. For example, the most recently modified results are at the top of the list (sort_by=-lastModifiedTime).
The following URL shows the default setting:
/customers?page=3&per_page=15&sort_by=-lastModifiedTime

Query parameters

ParameterDescriptionValid valuesDefault
orderControls the order in which results are returned.asc—ascending
desc—descending
desc
sort_byDefines the field by which the results are sorted.Depends on the resource being queried. For example:
date
id
Depends on the resource being queried. If the resource contains a date, then date is used as the default.

Ascending and descending results

TypeOrderExampleDescription
AlphabeticalAscendingA - ZFirst to last
AlphabeticalDescendingZ - ALast to first
NumericalAscending1 - 9Lowest to highest
NumericalDescending9 - 1Highest to lowest
DateAscending01-01-1970 - TodayOldest to newest
DateDescendingToday - 01-01-1970Newest to oldest

Paginating response results

Pagination parameters allow you to select and limit the number of results returned, and also to set how many results are displayed per page. For example, to display five pages starting on page 13, use the following parameters:
/customers?count=5&start_index=13

Pagination parameters

ParameterDescriptionValid valuesDefault
pageWhich page to returnAll
per_pageNumber of results to display per page1, 2, 5, 10, 20, 5010
offsetStarting page number to display1
countHow many pages to displayAll
start_dateStarting date of the records to display. YYYY-MM-DD
end_dateEnd date of the records to display. YYYY-MM-DD

Examples

Get balances

Pagination is optional.
https://sandbox.bond.tech/api/v0/balances?page=2&customer_id=725cb9df-43da-4063-9dd3-d62971c428af

  • page—Retrieve page 2 of the balances
  • customer_id—Retrieve the balances for customer ID 725cb9df-43da-4063-9dd3-d62971c428af

Get transactions

Pagination is optional.
https://sandbox.bond.tech/api/v0/transactions?customer_ID=725cb9df-43da-4063-9dd3-d62971c428af&start_date=2021-03-30&end_date=2021-04-10&count=15

  • count—Retrieve 15 pages of transactions
  • start_date—Retrieve transactions starting from Mar 30, 2021
  • end_date—Retrieve transactions ending on Apr 10, 2021
  • customer_id—Retrieve the transactions for customer ID 725cb9df-43da-4063-9dd3-d62971c428af

Next Steps