Versions Compared

Old Version 3

changes.mady.by.user Sergio Freire

Saved on

compared with

New Version 4

changes.mady.by.user Sergio Freire

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

...

Info
titleAm I using Jira server/datacenter or Jira Cloud?

So, you only know that you're using Jira or Xray but you don't know exactly which "flavour" (i.e., deployment type) you're using.

First, you can ask your Jira administrator. Besides, you can 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 you are using Xray on a Jira Cloud instance (i.e., "Xray Cloud").


The documentation for Xray Cloud can be found here.


Jira server/datacenter and Xray for Jira server/datacenter

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 are using Xray on a Jira server/datacenter instance.

Available APIs

There are several APIs that users can take advantage of.

Most users will the REST API provide 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.

Xray Cloud 


The documentation for Xray server/DC can be found here.


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.

Most users will the REST API provide 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.

Xray Cloud

Xray Cloud provides a REST API and also a, more advanced, GraphQL API.

Besides, there is also Jira's REST API in case you aim to interact with Jira itself and, for example, do CRUD operations on issues (except for testing data).


https://xray.cloud.getxray.app/api/v1/<resource_name>

https://xray.cloud.getxray.app/api/v2/<resource_name>

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.


API provided bytype of APIversionsURL syntaxauthenticationpurposenotes
1XrayREST APIAPI provided bytype of APIversionsURL syntaxauthenticationpurposenotes1XrayREST APIv1, v2

managed by Xray Cloud

  • API key (i.e., pair of Client Id + Client Secret created by Jira administrator)
  • authentication
  • importing test results
  • importing tests
  • import/exporting Cucumber scenarios
  • backups
This is the most used API, as it used for importing test automation results.2XrayGraphQLv1, v2

https://xray.cloud.getxray.app/api/

v2/graphql

v1/<resource_name>

https://xray.cloud.getxray.app/api/v2/<resource_name>


managed by Xray Cloud

  • API key (i.e., pair of Client Id + Client Secret created by Jira administrator)

Note: to make GraphQL requests, an initial REST API call needs to be made to the authentication endpoint

  • CRUD operations for Xray entities, with access to all data, including creation of tests
  • obtain Xray entities and other entities related to them, and manage these associations
  • export test results

This API cannot be used to import test automation results.

This API is more advanced and usually only required whenever implementing some custom scenarios.

3JiraREST APIv3

managed by Jira Cloud

  • basic authentication, OAuth 2.0
  • standard CRUD operations on Jira entities, including Jira issues (which includes Xray issue based entities)

This API does not provide ways of accessing/modifying internal Xray data, such as test steps, for example.

Xray server/DC

  • authentication
  • importing test results
  • importing tests
  • import/exporting Cucumber scenarios
  • backups
This is the most used API, as it used for importing test automation results.
2XrayGraphQLv2https://xray.cloud.getxray.app/api/v2/graphql

managed by Xray Cloud

  • API key (i.e., pair of Client Id + Client Secret created by Jira administrator)


Note: to make GraphQL requests, an initial REST API call needs to be made to the authentication endpoint

  • CRUD operations for Xray entities, with access to all data, including creation of tests
  • obtain Xray entities and other entities related to them, and manage these associations
  • export test results

This API cannot be used to import test automation results.

This API is more advanced and usually only required whenever implementing some custom scenarios.

3JiraREST APIv3

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.

managed by Jira Cloud

  • basic authentication, OAuth 2.0
  • standard CRUD operations on Jira entities, including Jira issues (which includes Xray issue based entities)

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.

Besides, there is also Jira's REST API in case you aim to interact with Jira itself and, for example, do CRUD operations on issues (except for testing data).


Info
titlePlease note
  • Xray server/DC doesn't provide a GraphQL API
  • Xray server/DC REST API is different from Xray Cloud REST API; some endpoints may be similar, like for importing test automation results, but there will be differences
  • Xray server/DC doesn't provide API Keys (pair client id + client secret), as it happens with Xray Cloud. Please check instead Personal Access Tokens (since v8.14, for Jira DC only)

API provided bytype of APIversionsURL syntaxauthenticationpurposenotes
1XrayREST APIv1.0, v2.0
API provided bytype of APIversionsURL syntaxauthenticationpurposenotes
1XrayREST APIv1.0, v2.0

<jira_base_url>/rest/raven/1.0/api/<resource_name>

<jira_base_url>/rest/raven/2.0/api/<resource_name>

managed by Jira server/DC

  • importing test results
  • import/exporting Cucumber scenarios
This is the most used API, as it used for importing test automation results.
2JiraREST APIlatest

<jira_base_url>/rest/raven/1.0/api/<resource_name>

<jira_base_url>/rest/

api/latest

raven/2.0/api/<resource_name>

managed by Jira server/DC

  • standard CRUD operations on Jira entities, including Jira issues (which includes Xray issue based entities)
This API does not provide ways of accessing/modifying internal Xray data, such as test steps, for example.

...

titlePlease note

...

  • importing test results
  • import/exporting Cucumber scenarios
  • obtain Xray entities and other entities related to them, and manage these associations
  • export test results
This is the most used API, as it used for importing test automation results.
2JiraREST APIlatest<jira_base_url>/rest/api/latest/<resource_name>

managed by Jira server/DC

  • standard CRUD operations on Jira entities, including Jira issues (which includes Xray issue based entities)
This API does not provide ways of accessing/modifying internal Xray data, such as test steps, for example.
Info
titleXray REST API v1 and v2 on Xray server/DC. What are the differences?

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

...