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. pagedetermines the page to return and per_page determines the number of items to return per page:

Parameter	Type	Description
page	integer	Number of page to return (default: first page)
per_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:

Attribute	Type	Description
page	integer	Number of page returned (or null for an empty result without any pages)
prev_page	integer	Number of previous page (or null without a previous page)
next_page	integer	Number of next page (or null without a next page)
last_page	integer	Number of last page (or null for an empty result without any pages)
per_page	integer	Maximum number of items returned per page
total	integer	Total number of items across all pages
result	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:

GET /api/v1/projects/1/runs

If there are more than 100 test runs in the project, a typical response can look as follows:

200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        { "id": 150, "name": "Run 150", .. },
        { "id": 149, "name": "Run 149", .. },
        { "id": 148, "name": "Run 148", .. },
        { "id": 147, "name": "Run 147", .. },
        ..
        { "id": 51, "name": "Run 51", ..}
    ]
    ..
}

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:

GET /api/v1/projects/1/runs?page=2

Testmo will then return the second page of test runs:

200 OK
{
    "page": 2,
    "prev_page": 1,
    "next_page": null,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        { "id": 50, "name": "Run 50", .. }
        { "id": 49, "name": "Run 49", .. }
        { "id": 48, "name": "Run 48", .. }
        { "id": 47, "name": "Run 47", .. }
        ..
        { "id": 1, "name": "Run 1", ..}
    ]
    ..
}

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:

GET /api/v1/projects/1/runs?expands=configs,milestones,users

Testmo will then include the expands as part of the expands attribute in the result:

200 OK
{
    "page": 2,
    "prev_page": 1,
    "next_page": null,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 150,
            "name": "Run 150",
            "config_id": 10,
            "milestone_id": 5,
            "created_at": "..",
            "created_by": 2,
            "closed_at": "..",
            "closed_by": 1
        },
        ..
    ],
    "expands" {
        "configs": [
            { "id": 10, "name": "Chrome" },
            ..
        ],
        "milestones": [
            { "id": 5, "name": "Release 1.0" },
            ..
        ],
        "users": [
            { "id": 1, "name": "User 1" }, // For closed_by
            { "id": 2, "name": "User 2" }, // For created_by
            ..
        ]
    }
}

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.