The SCG Messaging REST API provides functionality to retrieve multiple records via GET calls. These queries can return thousands of records which can slow down the API response time.
To address this, the API provides pagination functionality for retrieving and organizing the results of the API calls. Pagination is a logical concept that allows to group query results in smaller groups to make the handling of the API responses easier.
In the SCG REST API, the number of records returned by default, per GET call, is 50 records. If the query returns more than 50 records, the API pagination parameters should be used, to retrieve the rest of the records beyond the initial 50 records.
This document describes the API query parameters available to manage the pagination in the GET calls of the SCG Messaging API. It also provides a basic example of a paginated API call.
Parameters
The following are the available query parameters on the GET call to set up the results retrieval by pages:
- Sort: parameter to establish an ordered sequence retrieval of the GET resulting elements.
- Limit: the number of elements by page. Maximum set 100 (default 50).
- Offset: parameter to set the starting element for the retrieve (page).
Example
Let’s say we need to display all the messages sent in a range of dates in DELIVERED state. As we know the result probably will retrieve more than 50 messages in which case, the developer should design the program to retrieve the results in groups of N elements until it retrieves all the query resulting messages.
This design will lead us to perform multiple calls, one per page, to the API.
The API call for 100 elements pages of DELIVERED messages sent by July could be:
Sort = created_date
Limit = 100
Offset = For page 1: Offset = 0
For page 2: Offset = 100
For page n: Offset = 100 * (n-1)
The API calls for this example are shown next:
API call for page 1:
curl -L -X GET \
-H "Authorization: Bearer [TOKEN]" \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages?\
created_date=%5B2022-07-01T00%3A00%3A00.000Z%2C2022-07-31T23%3A59%3A59.999Z%5D&\
sort=created_date&\
state=DELIVERED&\
offset=0&\
limit=100
The resulting json will contain the first 100 DELIVERED messages sent in July (page 1).
API call for page 2:
curl -L -X GET \
-H "Authorization: Bearer [TOKEN]" \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages?\
created_date=%5B2022-07-01T00%3A00%3A00.000Z%2C2022-07-31T23%3A59%3A59.999Z%5D&\
sort=created_date&\
state=DELIVERED&\
offset=100&\
limit=100
The resulting json will contain the next 100 DELIVERED messages sent in July (page 2).
Subsequent calls to the API for next pages increasing the offset until the API call retrieve no messages.
0 Comments