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
| Parameter | Description | Valid values | Default |
|---|---|---|---|
order | Controls the order in which results are returned. | asc—ascendingdesc—descending | desc |
sort_by | Defines the field by which the results are sorted. | Depends on the resource being queried. For example:dateid | Depends on the resource being queried. If the resource contains a date, then date is used as the default. |
Ascending and descending results
| Type | Order | Example | Description |
|---|---|---|---|
| Alphabetical | Ascending | A - Z | First to last |
| Alphabetical | Descending | Z - A | Last to first |
| Numerical | Ascending | 1 - 9 | Lowest to highest |
| Numerical | Descending | 9 - 1 | Highest to lowest |
| Date | Ascending | 01-01-1970 - Today | Oldest to newest |
| Date | Descending | Today - 01-01-1970 | Newest 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
| Parameter | Description | Valid values | Default |
|---|---|---|---|
page | Which page to return | All | |
per_page | Number of results to display per page | 1, 2, 5, 10, 20, 50 | 10 |
offset | Starting page number to display | 1 | |
count | How many pages to display | All | |
start_date | Starting date of the records to display. YYYY-MM-DD | ||
end_date | End date of the records to display. YYYY-MM-DD |
Examples
Get balances
Pagination is optional.
https://sandbox.bond.tech/api/v0.1/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.1/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
Updated almost 2 years ago