Pagination & Expands
Testmo's API supports pagination to retrieve large API results in multiple pages (chunks). Many API methods accept pagination parameters so you can request more results with additional API calls.
Testmo's API also supports the concept of expands. When making API calls, responses often include references to related resources. For example, when retrieving a list of test runs, the returned runs include references to related users, configurations or milestones. You can ask Testmo to expand such related resources so that the API responses include these resources directly without sending extra API calls.
Pagination
Pagination is implemented with two request parameters, namely page
and per_page
. page
determines the page to return and per_page
determines the number of items to return per page:
integer
Number of page to return (default: first page)
integer
Maximum number of items to return (supported: 15
, 25
, 50
, 100
; default: 100
API methods that support pagination follow the same conventions and always include the following attributes in the response:
integer
Number of page returned (or null
for an empty result without any pages)
integer
Number of previous page (or null
without a previous page)
integer
Number of next page (or null
without a next page)
integer
Number of last page (or null
for an empty result without any pages)
integer
Maximum number of items returned per page
integer
Total number of items across all pages
array
List of items of the page
Example
As an example, consider getting the first page of test runs for a project with ID 1:
If there are more than 100 test runs in the project, a typical response can look as follows:
The response indicates that we have a total of 2 pages with a total of 150 test runs. To get the second (and last) page, we can simply add the page
parameter to the request as follows:
Testmo will then return the second page of test runs:
Important: if next_page
is null
or if page
equals last_page
, the returned page represents the last page of the result set and there are no additional pages to query. When requesting more than one page of items (especially in a loop), please make sure to handle this condition. Otherwise, your API access may be throttled or limited in case you send an unnecessary or excessive amount of requests.
Note that most API methods return the most recent items first (i.e. in descending order by creation date). Some API methods support additional parameters to customize this behavior, namely sort
and order
. Please refer to the documentation of those API methods for details.
Expands
Expands are supported by many Testmo API methods and make it easy to include referenced related resources in API results. This is helpful to simplify API access and to reduce the number of API calls you need to make. You can tell API methods to return such expands in the response by including an expands
request parameter as a comma-separated list of object types.
Example
An an example, to include referenced configurations, milestones and users when retrieving a page of test runs, you can include an expands
parameter as follows:
Testmo will then include the expands as part of the expands
attribute in the result:
Depending on the API method, Testmo supports the following types of expands:
automation_sources
configs
field_values
groups
issues
milestone_stats
milestone_types
milestones
roles
states
statuses
templates
users
Most expand types support the id
and name
attributes and some expand types also include additional attributes. You can find a full list of supported attributes in the OpenAPI schema.
Last updated
Was this helpful?