Configuring pagination
Pagination is a process that enables you to break up the number of records that are returned from a retrieve action into more manageable sizes.
The application using your connector then handles the pagination that you configured, and users of your connector need to select how many items they want to retrieve. For instance, if somebody was using your connector in App Connect, regardless
of the type of pagination you configured, users need to select the maximum number of items to retrieve, and then specify what to do if the limit is exceeded or if no items are found as demonstrated in the following screen capture. The manner
in which they are retrieved and broken down is all handled within the framework that consumes your connector.
The following table displays the pagination options that are available for you to select in the Connector Development Kit.
| Pagination type | Description |
|---|---|
| None | No pagination required |
| Page | Use ‘Page’ if the API supports page and size pagination |
| Skip and limit | Use ‘Skip and limit’ if the API supports offset pagination |
| Token | Use ‘Token’ if the API supports seek pagination |
In the Connector Development Kit, the option to configure pagination is only available for the retrieve actions with the action type 'RetrieveWithWhere'. To configure pagination in the Connector Development Kit, refer to the query parameters in the API documentation for your connector. If you used an OpenAPI document to create your connector, then the pagination parameters are populated from the information that is contained within the document. If required, you can also define them manually in the Request tab.
The following screen capture, for example, demonstrates how the limit query parameter is used in the Swagger Petstore REST API document. This OpenAPI document was used to create a connector in the Connector Development Kit. We can tell from this that the Skip and Limit pagination option is the most appropriate, and you can see how the limit query parameter is populated in the Query parameters section and then provided as an option in the Limit parameter pagination field.
Page
Use 'Page' if the API your connector is based on supports page and size pagination. 'Page' is useful when you want to jump straight to a specific page.
If you choose 'Page', you need to provide values for the following fields:
| Field | Description |
|---|---|
| Page number parameter | Select the parameter that provides the page number |
| Page size parameter (optional) | Select the parameter that provides the number of records to retrieve per page |
| Default page size | Specify the default number of records per page |
| Page start index | Select the number that represents the first page of the returned records, either 0 or 1 |
Skip and limit
Use ‘Skip and limit’ if the API that your connector is based on supports offset pagination. Skip and limit are used to return a specified amount of data starting from a specified position. It's useful for infinite scrollable lists, however, note that large loads take longer to process due to the number of records that need to be skipped with each request. Also, if an item is deleted, the process is disrupted, and records might be missed. If this is a concern then select 'Token' pagination.
If you choose ‘Skip and limit’, you need to provide values for the following fields:
| Field | Description |
|---|---|
| Skip parameter | Select the parameter that indicates how many items should be skipped |
| Limit parameter | Select the parameter that indicates the number of items to be returned |
| Default page size | Specify the default number of records per page |
Token
Use ‘Token’ if the API supports seek pagination. Token pagination uses the filter value of the last page to retrieve the next set of items. If you select this method then no items are missed if anything is deleted (as is the case with Skip and limit pagination).
If you choose ‘Token’, you need to provide values for the following fields:
| Field | Description |
|---|---|
| Token request parameter | Select the parameter that provides the token that is used to fetch the next page |
| Token page size parameter | Select the parameter that provides the number of records to retrieve per page |
| Default page size | Specify the default number of records per page |