api Object
| Key | JSON Type | Required |
|---|---|---|
| base_url | string | yes |
| pagination | object | no |
Default: '' (Empty String)
URL to use when referring to a service. Example: https://api.example.com/
Default: {} (Empty Object)
Describes how to retrieve multiple pages of API requests for a service.
This section specifies which pagination style is used. Currently we support the following styles: limit-offset, page-number and cursor.
Default: {}
Provides specific data to help with the pagination of API requests to retrieve all of the available data.
Please see below for a list of pagination styles and their parsers.
Example:
{
"pagination": {
"style": {
"type": "limitoffset",
"limit": {
"param": "limit",
"value": 50
},
"offset": {
"param": "offset",
"value": 0
}
},
"parser": {
"total_items": {
"!jq": ".total_items"
}
}
}
}
Limit-Offset Style:
| Key | JSON Type | Note |
|---|---|---|
| type | string | select this style by using "limitoffset" for this field |
| limit | object | this field has two required sub-keys: param (string): url param used to indicate limitvalue (integer): number of results to fetch per page |
| offset | object | this field has two required sub-keys: param (string): url param used to indicate offsetvalue (integer): starting position of data. |
When getting a response back from an API request, the [total_items]{.title-ref} is an action to identify the total number of items available as part of the API request.
For example, if a request is made to list the number of available forms the total number of forms could be 50; however, due to pagination each response only lists 10 forms at a time.
If the response from an API request contains the following data
{
"item_count": 300,
"items": []
}
Then the total_items action could utilize the !jq command to retrieve the total number of items.
{
"pagination": {
"parser": {
"total_items": {
"!jq": ".item_count"
}
}
}
}
See also: !jq
{
"pagination": {
"style": {
"type": "page",
"page_number": {
"param": "page",
"value": 1
},
"page_size": {
"param": "pageSize",
"value": 50
}
},
"parser": {
"total_pages": {
"!jq": "page_count"
}
}
}
}
| Key | JSON Type | Note |
|---|---|---|
| type | string | select this style by using "page" for this field |
| page size | object | this field has two required sub-keys: param (string): url param used to indicate page sizevalue (integer): number of results to fetch per page |
| page_number | object | this field has two required sub-keys: param (string): url param used to indicate pagevalue (integer): starting position of data, depending on how which indexing scheme (0 or 1) is used. |
When getting a response back from an API request, the [total_pages]{.title-ref} is an action to identify the total number of pages to request to list all items.
For example, if a request is made to list the number of available forms the total number of pages could be used to identify how many page request should be made to retrieve all data.
If the response from an API request contains the following data:
{
"total_pages_count": 6,
"items": []
}
Then the total_items action should utilize the !jq command to retrieve the total number of pages.
{
"pagination": {
"parser": {
"total_page": {
"!jq": ".total_pages_count"
}
}
}
}
See also: !jq
{
"pagination": {
"style": {
"type": "cursor",
"limit": {
"param": "limit",
"value": 200
},
"ordering":
"param": "asc",
"value": ""
}
},
"parser": {
"next_result_token": {
"!jq": ".next_cursor"
}
}
}
}
| Key | JSON Type | Note |
|---|---|---|
| type | string | select this style by using "cursor" for this field |
| limit | object | this field has two required sub-keys: param (string): url param used to indicate limitvalue (integer): number of results to fetch per page |
| ordering | object | this field has two required sub-keys: param (string): url param used to indicate ordervalue (integer): criteria to order the results Note: Both param and value values are dictated by the API. |
When getting a response back from an API request, the previous_result_token parser extracts the previous cursor from the response.
If the response from an API request contains the following data:
{
"previous_cursor": "kGAnBS4x",
"items": []
}
Then the previous_result_token parser should utilize the !jq command to retrieve the cursor value (kGAnBS4x)
{
"pagination": {
"parser": {
"previous_result_token": {
"!jq": ".previous_cursor"
}
}
}
}
When getting a response back from an API request, the next_result_token parser extracts the next cursor from the response.
If the response from an API request contains the following data:
{
"next_cursor": "cGFnZS0x",
"items": []
}
Then the next_result_token parser should utilize the !jq command to retrieve the cursor value (cGFnZS0x)
{
"pagination": {
"parser": {
"next_result_token": {
"!jq": ".next_cursor"
}
}
}
}
See also: !jq
Adding Additional Params to Pagination
Besides the fields listed above, all pagination styles also accept an optional key "extra".
This section is meant to support any custom params allowed in the API url such as filtering, ordering, etc. See below for details:
extra is where you can include additional - parameter, value pairs that should be included in pagination requests.
{
"pagination": {
"pagination_type": "pagenumber",
"parser": {
"page": {
"param": "pg",
"value": 1,
"step": 1
},
"extra": [
{"param": "sort", "value": "asc"}
]
}
}
}
The configuration above would result in a pagination request that would look similar to the following:
http://api.example.com?pg=1&sort=asc
Updated over 2 years ago