A few months ago, we added the capability for you to specify API query parameters by using a Retrieve with filter operation when creating flows for an API in IBM App Connect. In our latest update, we’ve enhanced the capability of Retrieve with filter to enable pagination for your retrieved records. Pagination allows your API to return a page of data on each invocation and can be configured by using the following query parameters:
- ‘limit’: States how many records to return.
- ‘skip’: Specifies a numeric offset to start returning records from.
- ‘token’: Defined as an arbitrary string that your API can use to identify where to start returning records from.
Once enabled in your flow (via a check box), you can configure pagination as follows:
- Indicate that you want use either ‘skip’ and ‘limit’ together, or ‘token’ and ‘limit’ when you make the API request. For example:
- If you want the API to return 2 records, starting from page 3, you can call the API by setting ‘limit’ to 2 and ‘skip’ to 3. In a traditional API call, this is equivalent to invoking the API using query parameters such as:
...?skip=3&limit=2.
- If you want the API to return 10 records at a time, you can call the API by setting ‘limit’ to 10 and specifying an arbitrary value for ‘token’ – equivalent to:
...?token=SomeValue&limit=10.
- Define values that should be returned for the pagination parameters in the response body. The response is returned as an object with an array of values or objects, as well as a
next object that contains values for the next page URL and limit, or the skip page offset and limit. The following image shows a sample response for an API call that includes ...?skip=3&limit=2 query parameters.
{
"next": {
"skip": 3,
"limit": 2
},
"repository": [
{
"name": "repository1"
},
{
"name": "repository2"
}
]
}
Let’s work through a simple flow design that demonstrates the pagination features.
Scenario
This scenario references the Bitbucket API, and uses its repositories resource to retrieve information about public repositories in the source control management hosting service.
As an API developer, you want to enable API consumers to retrieve records from their source code repositories by calling the API using their preferred ‘limit’ and ‘token’ values. This example focuses on an admin user who wants to obtain information about repositories that haven’t been maintained or used in a while, so that they can decide whether these “inactive” repositories can be archived.
The sample flow uses an HTTP node to retrieve records from the Bitbucket repositories resource using ‘limit’ and ‘token’ API query parameters, and then parses the response returned. If the repository hasn’t been updated since 2012-06-24, an email is sent from a Gmail node to the admin user, with details of the inactive repository and owner.
In App Connect on IBM Cloud, first create flows for an API with a model name of repository, and then define these properties for the model: uuid (used as the model’s ID field), name, and full_name.
For the repository model, define a Retrieve with filter operation that enables pagination support with ‘token’ and ‘limit’ parameters. Then click Implement flow to view a sample API request, add actions and specialized processing, and configure a response.
The following image shows example filter formats that are shown for the Request node.
After the Request node, add an HTTP node with an HTTP method of GET and specify the Bitbucket API URL using the following format: https://api.bitbucket.org/2.0/repositories?pagelen=limitValue&after=tokenValue. In the URL, map to the limit field from the Request node to set a dynamic value for limitValue, and map to the token field to set a dynamic value for tokenValue.
Next, add a JSON parser to parse the JSON string response that the HTTP node returns. In the JSON Input field, map to Response body.
Provide sample JSON of the response and click Generate Schema to transform the string into a JSON object with key/value pairs. You’ll be able to map to the keys in the JSON schema in subsequent nodes.
Now, add a For each node to iterate over the repository records (depicted by the values field) in the API response.
Add an If node with a condition that queries for any inactive repositories that have not been updated since 2012-06-24. Map to the updated_on field, which holds the “last updated” value in the response.
Add a Gmail node that sends an email to the admin user for each inactive repository found.
Now, return to the For each node and define the following Output properties: name, full_name, uuid, and ownerId. Expose these properties as fields and map to the results of the If node as shown in this image:
Finally, click the Response node and configure values for the next page token, limit, and repository records. Map the required fields as shown in the image and start the flow.
To test the flow, you can switch to the Manage tab to use the embedded API management capabilities in IBM App Connect on IBM Cloud. Expose and share the flow as an API, and then access the API Explorer window to use the built-in Try it facility to call the API. (For more information about using the embedded API management capabilities with an API flow, see the Managing APIs that are exposed by API flows in App Connect on IBM Cloud tutorial.) Call the API with query parameters by specifying a numerical value in the limit field and a date value in the token field, to get the records for that date.
Tip: This is equivalent to calling the API as follows: ../repository?limit=10&token=2008-08-23
Here’s a sample response from the API:
{
"next": {
"limit": 10,
"next_page_token": "2008-09-11T14%3A01%3A41.129182%2B00%3A00"
},
"repository": [
{
"full_name": "",
"name": "",
"uuid": ""
},
{
"full_name": "",
"name": "",
"uuid": ""
},
{
"full_name": "kkubasik/end-of-the-world",
"name": "End Of The World",
"uuid": "{320d4873-b242-488b-98a0-09054445a243}"
},
{
"full_name": "boredzo/pb",
"name": "pb",
"uuid": "{f5138b69-6d48-4731-ad4d-318962ebf40f}"
},
{
"full_name": "mronge/mailcore",
"name": "MailCore",
"uuid": "{2d6d4aae-2122-47cd-8b66-e36c4f1edf5e}"
},
{
"full_name": "weisjohn/endoftheworld_weisjohn_2",
"name": "endoftheworld_weisjohn_2",
"uuid": "{662c8bbd-f6d3-4b94-a070-df1c0be577d9}"
}
]
}
Also check for messages about inactive repositories that were sent to the admin user from the Gmail account in your flow. For example:
Additional notes