Page History
| Table of Contents |
|---|
Overview
If you aim to interact with Xray data, there are a bunch of APIs you can use for different purposes.
...
- Am I using Xray on Jira server/datacenter or Xray on Jira Cloud? This is crucial as these are different products, using different technologies, providing slightly different APIs.
- What do I aim to do? This is important to select the proper API to invoke; the format of the API call may be different even if there is a similar API endpoint for the other deployment type.
- Which authentication mechanism do I want to use on the API calls? This is mostly dependent on the previous answers.2
This page will help you out answer these questions.
Xray server/DC vs Xray Cloud
Although similar, Xray for Jira server/Data Center(DC) and Xray for Jira Cloud are different products, essentially because they are built on top of different infrastructures and application capabilities. Jira server/datacenter and Jira Cloud are also distinct products, with different roadmaps, built using distinct technologies, and providing different APIs. This has a consequence that apps for Jira server/DC and for Jira Cloud are essentially totally different from an architecture standpoint, but eventually also from a feature perspective.
...
Now that you know the Jira "flavour" (i.e., deployment type) being used and the corresponding Xray product variant (whether Xray Cloud or Xray server/DC), let's see which APIs are available in that context, how they work and for that they can be used for.
Available APIs
There are several APIs that users can take advantage of.
APIs can either be provided by Xray or by Jira itself.
Most users will use the REST API provide provided by Xray to import test automation results during CI/CD. Please have in mind that, in this case, Xray Cloud's REST API is a different API than the Xray server/DC' REST API.
The Jira REST API is only used in case you want to perform operations on Jira data, such as standard CRUD operations (Create, Read, Update, Delete) on issues or, for example, search for issues using JQL. Jira Cloud and Jira server/DC have similar (not equal) REST APIs.
Xray Cloud
Xray Cloud provides a REST API and also a, more advanced, GraphQL API.
...
| API provided by | type of API | versions | URL syntax | authentication | purpose | notes | |
|---|---|---|---|---|---|---|---|
| 1 | Xray | REST API | v1, v2 | https://xray.cloud.getxray.app/api/v1/<resource_name> https://xray.cloud.getxray.app/api/v2/<resource_name> |
|
| This is the most used API, as it used for importing test automation results. |
| 2 | Xray | GraphQL | v2 | https://xray.cloud.getxray.app/api/v2/graphql |
Note: to make GraphQL requests, an initial REST API call needs to be made to the authentication endpoint |
| This API cannot be used to import test automation results. This API is more advanced and usually only required whenever implementing some custom scenarios. |
| 3 | Jira | REST API | v3 | https://<site_url>/rest/api/3/<resource_name> Note: <site_url> can be something like <xxx>.atlassian.net or it can be your own domain, in case you have it defined for your Jira cloud instance. |
|
| This API does not provide ways of accessing/modifying internal Xray data, such as test steps, for example. |
Xray server/DC
Xray server/DC only provides a REST API, used to import test automation results and also to obtain and manage relations between Xray entities.
...
| Info | ||
|---|---|---|
| ||
The REST API v2.0 for Xray server/DC is an extension to the original v1.0 of the REST API. Therefore, all existing endpoints on v1.0 also exist on v2.0 (even if you don't see that in the docs); you just need to replace the "1.0" by "2.0" on the URL. Example: <jira_base_url>/rest/raven/1.0/api/test/{key}/testexecutions becomes <jira_base_url>/rest/raven/2.0/api/test/{key}/testexecutions |
Use cases
Importing test automation results to Xray using Xray JSON format
Importing automation results into Xray is a very common use case.
...
On the failed test, we leave a comment on the Test Run and also attached a screenshot as evidence.
Xray server/DC
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
curl -H "Content-Type: application/json" -X POST -u jira_username:jira_password --data @payload.json https://jiraserver.example.com/rest/raven/2.0/import/execution |
...
After importing results, a Test Execution would be created containing the results for the two tests; the details of the execution screen show the data of the Test Run, including its status, comment, timings, among other.
Xray Cloud
The first thing to do would be to obtain a token, using the Client Id and Client secret from the corresponding API key on Xray.
...
After importing results, a Test Execution would be created containing the results for the two tests; the details of the execution screen show the data of the Test Run, including its status, comment, timings, among other.
References
- Xray server/DC and Jira server/DC
- Xray Cloud and Jira Cloud
- Xray Code Snippets (open-source project with code samples, using different languages)
- Xray Postman collections (Postman collections showcasing usage of APIs both for Xray server/DC and Xray Cloud, including REST and GraphQL examples)
- Other useful resources