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:

1 Getting Started
- 1.1 Cloud
  - 1.1.1 URL
  - 1.1.2 Authentication
  - 1.1.3 Swagger Documentation
- 1.2 Server / Data Center
  - 1.2.1 URL
  - 1.2.2 Authentication
  - 1.2.3 Swagger Documentation
2 API Details
3 Postman Collection
4 Understanding Permissions in API Responses

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’.

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.

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.

Cycle Operations- Cycle operations like creating a cycle and deletion of cycle
- Create new cycle- A new cycle gets created with details about the cycle.
- Create new cycle from set- A new cycle gets created and cases from the set are added to the cycle.
- Delete Cycle
Execution Results & Case/Run Management- The following actions can be performed via this API call.
- Add Case to a Cycle- Existing cases can be added to a Cycle.
- Add new Run for an existing Cases in a Cycle- New runs can be added for cases already in the Cycle.
- Add case or run and mark the basic result of a case in cycle- Mark execution results for cases/runs in a Cycle.
- Get Case Association list- Get a paginated list of all Case associations (Case, Association and Latest Run) in a Cycle.
- Get all Cases with all runs- Get a paginated list of all Runs grouped by Case Association in a Cycle.
- Get the Latest Run- Get the latest Run for a Case in a Cycle.
- Get run details by run ID- Get all details of a specific run in a test case.
- Attach evidence to the latest test run of a case- Attach files to a case execution.
- Attach evidence to run by run ID- Attach files to a specific run.
- Attach evidence to a step in a run- Attach files to a specific step in a run.
- Update the entire run including steps- Update comments, defects, status, and actual results at run and step level.
- Import Automated Test Results- This API can be used for uploading test automation execution results.
- Reset a run- Reverts a run to its original status of Not Run and removes all artifacts.
Case Information- The following GET calls can be used to get the list of cases and details of a case and map for different attributes defined for the project.
- Case Details- Get case metadata like folder, tags, title, owner, status, etc.
- Create Case- Create a case with basic details.
- Case List- Get a paginated list of cases for the given project key.
- Search Case- Get a paginated list of Cases matching the provided search criteria.
Traceability- This call returns traceability information for specified Jira Issue IDs.
- Traceability information- Get a list of Cases associated with a Requirement/Jira issue ID. It will also return the latest Run information for the Case. Runs will be sorted in Descending order of the Created date.
Migration- These calls can be used to migrate data.
- Migrate Run- Migrate Run to for a Case to a Cycle. This allows creating a back-dated entry for the Run.

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.