Pagination strategies

Pagination strategies refer to the various techniques and approaches used to manage and navigate large sets of data or resources in a systematic and efficient manner. Pagination is commonly employed in software applications, particularly web applications and APIs, to break down extensive datasets into smaller, more manageable chunks or pages. This enables users to browse through the data incrementally, enhancing usability and performance.

OpenAPI specification offers extensions that extend the capabilities of the OpenAPI Specification (OAS) beyond its core functionality.

• These extensions are used to provide more detailed documentation, specify custom behavior, or include metadata that is not covered by the standard specification.

• Extensions are denoted by keys prefixed with x-adeptia in the OpenAPI document.

Adeptia introduces the following extension to define the pagination strategies in the standard Open API specification.

Adeptia supports the following pagination strategies

1. OffsetIncrement:

   • Offset increment based pagination is a pagination technique that uses parameters to specify the number of items to retrieve per page (limit) and the starting point in the dataset (offset).

   • The "Offset Increment" refers to how much you increase the offset for each subsequent page.

2. PageIncrement:

   • Page increment based pagination is a pagination technique that uses parameters to specify which particular page to retrieve.

   • Instead of using an offset, it relies on the concept of page number, where each request specifies the page number to retrieve.

3. CursorPagination:

   • Cursor-based pagination is an alternative pagination strategy often used in REST APIs, particularly for large datasets.

   • Instead of relying on page numbers or offsets, cursor pagination uses a "cursor" that points to a specific item in the dataset.

   • This approach is useful for scenarios where the dataset can change frequently, and using offsets or page numbers may result in inconsistent or missing data.

Defining OffsetIncrement strategy

Field name	Description	YAML
strategyName	The user-defined name for the pagination strategy.	<ch:codesample></ch:codesample>
type	The type of pagination strategy. It can be one of the following: OffsetIncrement PageIncrement CursorPagination	<ch:codesample></ch:codesample>
default	When multiple pagination strategies are defined, setting one as the default involves specifying which strategy should be used by default when no specific strategy is explicitly selected.	Possible values: true, false <ch:codesample> </ch:codesample>
pageSize	The number of results to be retrieved per page, often referred to as "items per page" or "page size", specifies the maximum number of items or records that will be included in each page of paginated results.	<ch:codesample></ch:codesample>
startFrom	The parameter specifying the page number from which pagination should begin is commonly referred to as the "starting page" or "initial page." This parameter determines the initial page of results to be retrieved when performing pagination.	<ch:codesample></ch:codesample>
pageSizeOption	The "Page Size" parameter settings. It defines the parameters related to the number of items or entries displayed per page and Specifies the method for including the page size in the request. This parameter has sub-parameters. See Pagination strategies | Request Option Parameters.	<ch:codesample></ch:codesample>
pageTokenOption	The "Page Token" parameter settings. The "Page Token" parameter settings in pagination defines how a token used for pagination is configured. This parameter has sub parameters. See Pagination strategies | Request Option Parameters.	<ch:codesample></ch:codesample>
stopCondition	Pagination stopCondition refers to the criteria or conditions that determine when the pagination process should stop retrieving or displaying additional data. See Pagination strategies | Defining Stop Condition.	<ch:codesample> </ch:codesample>

Request Option Parameters

Field name	Description	YAML
name	The name of the parameter to be included in the request.	<ch:codesample></ch:codesample>
injectAs	Specify the method of including the parameter in the request.   Possible Values: query header	<ch:codesample></ch:codesample>
appendToExistingParamName	Define the parameter name if a value needs to be appended to an existing parameter value, the parameter name remains unchanged. Only the value of the parameter is modified by appending or adding the new value to the existing value.	<ch:codesample> </ch:codesample>
nameSeparator	Refers to a delimiter or character used to append a parameter name when appending to an existing parameter.	<ch:codesample></ch:codesample>
valueSeparator	Refers to a delimiter or character used to append a parameter value within an existing parameter's value when appending to an existing parameter.	<ch:codesample> </ch:codesample>

Example: OffsetIncrement pagination strategy definition for the QuickBooks application

Defining PageIncrement strategy

Field name	Description	YAML
strategyName	The user-defined name for the pagination strategy.	<ch:codesample> </ch:codesample>
type	The strategy type, it can be one of the following: OffsetIncrement PageIncrement CursorPagination	<ch:codesample> </ch:codesample>
default	When multiple pagination strategies are defined, setting one as the default involves specifying which strategy should be used by default when no specific strategy is explicitly selected.	Possible values: true, false <ch:codesample> </ch:codesample>
pageSize	The number of results to be retrieved per page, often referred to as "items per page" or "page size", specifies the maximum number of items or records that will be included in each page of paginated results.	<ch:codesample> </ch:codesample>
startFrom	The parameter specifying the page number from which pagination should begin is commonly referred to as the "starting page" or "initial page." This parameter determines the initial page of results to be retrieved when performing pagination.	<ch:codesample> </ch:codesample>
pageSizeOption	The "Page Size" parameter settings. It defines the parameters related to the number of items or entries displayed per page and Specifies the method for including the page size in the request. This parameter has sub-parameters. See Pagination strategies | Request Option Parameters.	<ch:codesample> </ch:codesample>
pageTokenOption	The "Page Token" parameter settings. The "Page Token" parameter settings in pagination defines how a token used for pagination is configured. This parameter has sub-parameters, see Pagination strategies | Request Option Parameters	<ch:codesample></ch:codesample>
stopCondition	Pagination stopCondition refers to the criteria or conditions that determine when the pagination process should stop retrieving or displaying additional data. See Pagination strategies | Defining Stop Condition	<ch:codesample> </ch:codesample>

Example: PageIncrement pagination strategy definition for the Xero application

Defining CursorPagination strategy

Field name	Description	YAML
strategyName	The user-defined name for the pagination strategy.	<ch:codesample> </ch:codesample>
type	The strategy type, it can be one of the following: OffsetIncrement PageIncrement CursorPagination	<ch:codesample> </ch:codesample>
default	When multiple pagination strategies are defined, setting one as the default involves specifying which strategy should be used by default when no specific strategy is explicitly selected.	Possible values: true, false <ch:codesample> </ch:codesample>
pageSize	The number of results to be retrieved per page, often referred to as "items per page" or "page size", specifies the maximum number of items or records  that will be included in each page of paginated results.	<ch:codesample> </ch:codesample>
startFrom	The parameter specifying the page number  from which pagination should begin is commonly referred to as the "starting page" or "initial page." This parameter determines the initial page of results to be retrieved when performing pagination.	<ch:codesample> </ch:codesample>
pageSizeOption	The "Page Size" parameter settings. It defines the parameters related to the number of items or entries displayed per page and Specifies the method for including the page size in the request. This parameter has sub-parameters. See Pagination strategies | Request Option Parameters	<ch:codesample> </ch:codesample>
pageTokenOption	The "Page Token" parameter settings. The "Page Token" parameter settings in pagination  defines how a token used for pagination is configured. This parameter has sub-parameters, see Pagination strategies | Request Option Parameters	<ch:codesample> </ch:codesample>
cursorInfo	Refers to the information associated with a cursor used to navigate through paginated results. This information often includes details such as the position of the current cursor, the direction of pagination (forward or backward), and any other metadata needed to resume pagination from a specific point. See Pagination strategies | CursorInfo Parameters	<ch:codesample>   </ch:codesample>
stopCondition	Pagination stopCondition refers to the criteria or conditions that determine when the pagination process should stop retrieving or displaying additional data. See Pagination strategies | Defining Stop Condition	<ch:codesample> </ch:codesample>

CursorInfo Parameters

Field name	Description	YAML
fetchFrom	Specifies where the cursor information should be retrieved from	Possible values: header, body <ch:codesample> </ch:codesample>
headerName	Specifies the name of the header from which to fetch the cursor information Only applicable when fetchFrom is set as Header	<ch:codesample> </ch:codesample>
relName	Indicates the relationship type of the cursor information being fetched.	<ch:codesample> </ch:codesample>
urlType	Specifies the type of URL associated with the cursor information. It's set to 'relative', suggesting that the URL provided in the cursor information is relative to the current page's URL. Possible Values: absolute relative	<ch:codesample> </ch:codesample>
cursorParam	Defines the name of the parameter used to encapsulate the cursor information	<ch:codesample> </ch:codesample>

Example: CursorPagination strategy definition for the Shopify application

Defining Stop Condition

• The stop condition in pagination refers to the criterion or criteria used to determine when the pagination process should cease.

• It defines the condition that once met, indicates that no further pages need to be fetched or displayed.

• This condition could be based on various factors, such as reaching the end of the dataset, fulfilling a specific condition.

• The stop condition ensures that the pagination process is efficient and does not continue indefinitely.

Field name	Description	YAML
StopConditionName	Provides a placeholder name for the stop condition. The name can be any one of the following: RecordCount ResponseHeader ResponseBody	<ch:codesample> </ch:codesample>
operationId	Specifies the operation Id for the endpoint to be used to retrieve relevant data If the operation Id is present, it should be utilized to make an API call to retrieve the total record count from the API. This operation Id typically represents a specific endpoint or function within the API that is responsible for fetching the total record count. The API call should be constructed using this operation Id, and upon successful execution, it should return the total record count, which can then be used in the pagination process. If the operation Id is not present, the response of the first API call should be used to retrieve the total record count. This involves parsing the response data returned by the initial API call to extract the total record count information. The structure of the response data and the location of the total record count within it would need to be identified, typically using a JSONPath or similar method, as indicated by the path attribute in the YAML configuration.	<ch:codesample> </ch:codesample>
params	Defines parameters required for the operation when operation Id is specified.	<ch:codesample> </ch:codesample>
concurrency	Only applicable for Record Count stop condition. To define the number of pages to be retrieved in parallel when the API supports parallel pagination, you can specify the concurrency level. This parameter determines how many simultaneous requests can be made to fetch data during the pagination process. Increasing the concurrency level allows for faster retrieval of data but may also place a higher load on the server. The appropriate concurrency level depends on factors such as server capacity, network bandwidth, and the API's rate limits.	<ch:codesample> </ch:codesample>
headerName	Only applicable for Response Header stop condition. The header value to look for to identify the end of pagination often depends on the API or service being used. However, in many cases, the "Link" header is utilized to provide pagination-related information, including links to the next or previous pages. However, it's essential to consult the API documentation to determine the specific header value or indicator used to signify the end of pagination for that particular API.	<ch:codesample> </ch:codesample>
path	Only applicable for Record Count and Response Body stop condition. The JSON path that indicates the total record count in the JSON response. If you're using a Response Body stop condition to identify the end of pagination and the end of pagination is signaled by a specific field or value in the response body, you would specify the JSON path to that field or value.	<ch:codesample></ch:codesample> <ch:codesample></ch:codesample>
value	The value that typically indicates the end of pagination	<ch:codesample> </ch:codesample>
isNull	If the API or service you are working with follows the convention where a null value marks the end of pagination, then it means that receiving a null value in a specific field or parameter indicates that there are no more pages to paginate through. This null value serves as a signal to stop requesting further pages, as there is no additional data available beyond that point.	<ch:codesample> </ch:codesample>