Rest APIs

The AIO Tests REST APIs provide programmatic integration with AIO Tests from any test framework in any language.

AIO Tests exposes endpoints to create execution cycles, report status for test case executions and get cycle details and summary for external reporting. The REST APIs give the flexibility to seamlessly integrate your automated tests, written in any language, into AIO Tests and get a single view of all automated and manual execution in one place.

This guide explains the authorization mechanism and gives an overview of the available APIs.

In this documentation, you’ll understand:

Getting Started

Cloud

URL

The APIs are available at the following base URL: https://tcms.aiojiraapps.com/aio-tcms/api/v1/

The older API URL has been deprecated (https://tcms.aioreports.com/aio-tcms/api/v1/). It will continue to work but it is recommended to move to the new base URL.

Authentication

Requests made to AIO Tests REST APIs must be authenticated with an Access Token. More information is available here.

Swagger Documentation

AIO Tests APIs can be tried out on this Swagger page - https://tcms.aiojiraapps.com/aio-tcms/aiotcms-static/api-docs/
This page can be easily accessed by clicking on the question icon on the top right of the app and clicking ‘API Reference’.

image-20240221-114529.png

The authorization token generated can be used using the Authorize button on the Swagger page.

Server / Data Center

URL

The APIs are available at following base URL: https://<jira_server_hostname>/<jira_context_path>/rest/aio-tcms-api/1.0/

For ex: If Jira is hosted on https://jira8.aiojiraapps.com, then REST APIs will be available at https://jira8.aiojiraapps.com/rest/aio-tcms-api/1.0/.

Authentication

Requests made to AIO Tests REST APIs must be authenticated via Basic authentication or PAT authentication. More information is available here.

Swagger Documentation

AIO Test APIs can be tried out via the Swagger page.
This page can be easily accessed by clicking on the question icon on the top right of the app and clicking ‘API Reference’.
APIs available in the Swagger documentation depend on the AIO Tests plugin version you have installed.

image-20240221-115550.png

Click on the Authorize button on the Swagger page to provide Jira Username and Password (Basic Authentication) to authenticate and try out the APIs.

API Details

The following AIO Tests APIs have been exposed. Details around each of these APIs can be found in Swagger documentation.

  • Configuration: Get Project-level configuration (Statuses, Folders, Tags etc.)

    • Tags of the project- Get a list of the Tags (ID and Name) defined within AIO Tests for a given Jira Project. These details can be used to attach specific tags while creating new cycles.

    • Case Status list- Get a list of the available Case Statuses (Draft, Published, Deprecated, etc.)

    • Case Automation Status list- Get a list of the Case Automation Statuses (Manual, To Be Automated, Automated, etc.)

    • Case Type list- Get a list of the Case Types defined for the project (Unit, Integration, Functional, etc.)

    • Case Priority list- Get a list of the Case Priorities defined for the project (Critical, High, Low, etc.)

    • Case Script Type list- Get a list of the Case Priorities defined for the project (Classic, BDD/Gherkin etc.)

    • Run Status list- Get a list of the available Run Statuses (Passed, Failed, Blocked, etc.). These IDs can be used while updating the status of existing cases in a cycle or to understand the test run distribution returned by the Get Cycle Summary call.

    • Project Configuration- Get all project configurations in one call. The response will return a list of Case Status, Case Automation Status, Case Type, Case Priority, Case Script Type, and Run Status.

  • Cycle Information: Following GET calls can be used to get different details of a cycle.

    • Cycle Details- Get cycle metadata like folder, tags, name etc.

    • Cycle Summary- Get cycle summary details like estimated and actual effort, total cases and run status distribution.

    • Cycle List- Get a paginated list of Cycles under the Project.

    • Search Cycle- Get a paginated list of Cycles matching the provided search criteria.

    • Cycles Folder Tree- Get the folder tree for Cycles. The IDs of the folders can be used to create new cycles in specific folders.

    • Cases of a Cycle- Get a paginated list of Cases associated with the specified Cycle. It will also return the latest run information for the Case like run status, associated defects, etc.

    • Latest Run information of Case in Cycle- Get the latest Run details of a Case in a Cycle. This API can be used to check the Run status, Actual Effort etc.

Postman Collection

You can also use the below sample Postman Collection to try out the Public APIs.
Download and Import the collection into Postman.

In the Postman collection, few collection-level variables have been defined. Either update the variables directly in the requests or navigate to Edit Collection and update the variable values as per your Jira instance values (Refer to the below screenshot).

Understanding Permissions in API Responses

With the introduction of the Cross-Linking feature (release 2.1), Cases from different Projects can be added to a Cycle. Users who do not have access to a project, will not be able to access the Case / Run from that project in the Cycle.

To indicate the access user has on different Entities - Case / Cycle & Run, the Permission object will be returned in response.

Sample Permission object is below:

"permission": { "value": 7, "error": null }
  • Permission object has value and error properties.

  • Value is a bit map where in bits from right to left represent the Delete, Write & Read permissions.
    7 - Full access (Delete, Write, Read)
    3 - Only Write and Read
    1 - Only Read
    0 - No permission

  • Error is an enum indicating why the user does not have access over the cycle.
    The error can be one of:

    • EVALUATION_FAILED- There was an error while evaluating the permission value.

    • JIRA_PROJ_NO_ACCESS- The user does not have access to the entity as the User does not have permission on the entity’s Project.

    • AIO_TESTS_DISABLED_PROJ- The user does not have access to the entity as AIO Tests have been disabled for the entity’s Project.

    • AIO_TESTRUN_REFSTEP_NO_ACCESS- The user does not have access on the Run as one of the Referenced Step Cases is not accessible.

  • If a user has permission (the error value is null), then an error will not be returned in the response.

 

The below table shows the Permission Values and Delete / Write / Read access it indicates.
If the bit is ON (having value 1), it means the user has permission to perform those operations.

Permission

Bit Map

Value

Delete

Write

Read

7

1

1

1

3

0

1

1

1

0

0

1

0

0

0

0

 The below table shows the Run permissions based on the corresponding Cycle and Case access.

The user who has Read-only access to Run, will not be able to change the status of a run, but would be able to view its data. On trying to update such a Run using the API will return a 4xx response.

Project Access

Run Permission

Cycle

Case

Linked Step in Case

Value

Y

Y

Y

7 (All)

Y

Y

N/D

1 (Read)

Y

N/D

-

1 (Read)

N/D

-

-

0 (No Access)

 

Y - User has access on the entity's project

N - User does not have access on entity's project

D - User has access, but AIO Tests is disabled

For further queries and suggestions, please feel free to reach out to our customer support service via help@aiotests.com.