Page History
| Table of Contents |
|---|
Overview
If you aim to interact with Xray data, directly or indirectly, there are a bunch of several APIs you can use for different purposes.
But first, you need to answer:
- Am I using Xray on Jira serverServer/datacenter 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 in order to select the proper API to invoke; the format of the API call may be different even if there is a are similar API endpoint endpoints 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.
This page will help helps you out answer these questions.
At In the end, you'll find all relevant references with links to the proper documentation.
...
| Info | ||
|---|---|---|
| ||
This article aims to provide you with the means to identify the Xray and Jira variants you have, along with the respective APIs that you can use. It also details the available authentication mechanisms. This is neither a "best practices" article nor an extensive API documentation; please check the relevant API documentation for the later latter (references at the end). |
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 serverServer/datacenter 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 serverServer/DC and for Jira Cloud are essentially totally different from an architecture standpoint, but eventually also from a feature perspective.
The Xray Cloud product closely integrates with Jira Cloud; each one uses their its own infrastructure, the first managed by Xray and the later latter managed by Atlassian.
Xray server/DC works on top of (i.e., deployed into) Jira server/DC, reusing the Jira server/DC infrastructure.
...
| Info | ||
|---|---|---|
| ||
So, now that you only know that you're using Jira or Xray but you don't know exactly which "flavourflavor" (i.e., deployment type) you're using. First, you can ask your Jira administrator. Besides, you You can also easily check for yourself. Jira Cloud and Xray for Jira Cloud If you see a top menu like the following one, having on the top-left corner to switch between Atlassian apps, followed by "Your work", "Filters", ... "Apps", then you are using a Jira Cloud instance.
If you click on a project that is using Xray, then the project left side menu will show you a "Testing Board" shortcut (and no Xray Reports, Xray Test Repository, Xray Test Plan Board, or Automated Steps Library). This telld tells you are using Xray on a Jira Cloud instance (i.e., "Xray Cloud").
The documentation for Xray Cloud can be found here. Jira serverServer/datacenter Datacenter and Xray for Jira serverServer/datacenterDatacenter If you see a top menu like the following one, having on the top-left corner an icon, just to go some Jira page (depending on your profile settings), followed by "Dashboard", "Projects", "Issues", ..., and then "Tests", then you are using a Jira server/datacenter instance. The "Tests" top menu shortcut only appears if you have Xray (for Jira server/datacenter) installed.
If you click on a project that is using Xray, then the project left side menu will show you some options from Xray. Xray Reports, Xray Test Repository, Xray Test Plan Board, and Automated Steps Library are great tips that tell you you are using Xray on a Jira server/datacenter instance.
The documentation for Xray server/DC can be found here. |
...
Now that you know the Jira "flavourflavor" (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, and what they can be used for.
Available APIs
There are several APIs that users can take advantage of.
...
Most users will use the REST API 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 serverServer/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 orof, for example, search for issues using JQL. Jira Cloud and Jira serverServer/DC have similar (not equal) REST APIs.
APIs available in Xray Cloud context
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 is 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. |
...
API available in Xray server/DC context
Xray serverServer/DC only provides a REST API, used to import test automation results and also to obtain and manage relations between Xray entities.
...
| API provided by | type of API | versions | URL syntax | authentication | purpose | notes | |
|---|---|---|---|---|---|---|---|
| 1 | Xray | REST API | v1.0, v2.0 | <jira_base_url>/rest/raven/1.0/api/<resource_name> <jira_base_url>/rest/raven/2.0/api/<resource_name> |
|
| This is the most used API, as it is used for importing test automation results. |
| 2 | Jira | REST API | latest | <jira_base_url>/rest/api/latest/<resource_name> |
|
| This API does not provide ways of accessing/modifying internal Xray data, such as test steps, for example. |
| 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.
...
In this case, we'll use the Xray JSON format as means to encapsulated encapsulate the test results.
At a high - level, the flow can be depicted in the following diagram.
...
| Expand | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
Xray JSON format has the same syntax but to the distinct nature of Jira serverServer/DC and Jira Cloud (and also Xray), there are some nuances.
|
In this case, we're assuming:
- Test issue(s) already exist in Xray (they could have been created as usual by a user or by some automation process)
- An automated test equivalent exist exists in the external tool/code, for each Test
...
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 otherothers.
Xray Cloud
The first thing to do would be to obtain a token, using the Client Id and Client secret Secret from the corresponding API key on Xray.
This would require performing a an HTTP request to the authentication REST API endpoint from Xray Cloud.
Then a second request could be made to upload the test automation results; in the following example, the Xray JSON is stored on a payload.json file.
...
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 otherothers.
Importing test automation results to Xray using other
...
formats (non-Xray JSON)
Besides the Xray JSON format as described on in the previous scenario, Xray also can import and process test automation results from reports stored in different formats (e.g., JUnit XML, NUnit XML, Cucumber JSON, etc).
This will make use of Xray Cloud REST API or Xray server/DC REST API.
In this case, what's important to have in mind is that:
- the supported test automation report formats may be different between Xray Cloud and Xray serverServer/DC
- the authentication mechanism is different in Xray Cloud and on Xray serverServer/DC
- HTTP POST request for the REST API call is slightly different for Xray Cloud and Xray serverServer/DC
Therefore, make sure you are using the proper documentation of the REST API, either Xray Cloud REST API or the Xray server/DC REST API one.
...