Page tree

This is the documentation of Xray Server. If you are looking for Xray Cloud, visit this page. Documentation of older versions of Xray Server is available in this page.

Skip to end of metadata
Go to start of metadata

The Xray REST API provides the following endpoints for managing the Test Repository information of a given project.

Some endpoints support pagination, using the page and limit query parameters.

Hierarchy

  • To obtain a list of all Test Repository folders of a given project, including their hierarchy information, you need to specify the key of the respective project.

 GET /rest/raven/1.0/api/testrepository/<projectKey>/folders

Returns a JSON object with a list of the folders of the Test Repository.

Request

PATH PARAMETERS
parametertypedescription
projectKeyString

project key

Example Request

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/<projectKey>/folders

Responses

200 OK : application/json : Successful. Returns a JSON object.


Each folder will provide some information, including:

  • id: internal folder Id; "-1" corresponds to the Test Repository root folder
  • rank: rank of the folder in the parent folder ("1" corresponds to the first element)
  • name: folder's name
  • testRepositoryPath: the full Test Repository path of this folder
  • folders: sub-folders
  • testCount: count of direct child Tests
  • totalTestCount: total count of all childs Tests

Example Output
{
"folders": [
  {
   "id": 6,
   "rank": 1,
   "name": "Folder1",
   "testRepositoryPath": "/Folder1"
   "folders": [],
   "testCount": 0,
   "totalTestCount": 0
  },
  {
   "id": 7,
   "rank": 2,
   "name": "Folder2",
   "testRepositoryPath": "/Core",
   "folders": [
     {
       "id": 8,
       "rank": 1,
       "name": "Sub2",
       "testRepositoryPath": "/Core/UI", 
       "folders": [],
       "testCount": 1,
       "totalTestCount": 1
      },
      {
       ...
      }
    ],
    "testCount": 0,
    "totalTestCount": 3
   }
  ],

}

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500  INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folders.

Tests

  • To obtain a list of the Tests associated with the Test Repository of a given project, you need to specify the key of project
  • To obtain a list of the Tests contained within a given Test Repository folder, you need to specify its folderId, besides the project key
  • To change (add/remove) Tests to a given folder, you need to specify the key of the respective project

 GET /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests

Returns a JSON object with a list of the Tests contained in a given folder of the Test Repository.

This endpoint supports pagination.

Request

PATH PARAMETERS
parametertypedescription
projectKeyString

project key

folderIdIntegerinternal folder Id; "-1" corresponds to the root folder of the Test Repository


QUERY PARAMETERS
parametertypedescription
allDescendants
Boolean

include all descendants (i.e. all child Tests); "false", by default

pageIntegerpage of paginated data (first 1)
limitIntegeramount of Tests per paginated data

Request examples

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver//rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests?allDescendants=true


Responses

200 OK : text/plain : Successful. Returns a JSON object containing the Tests.


Each test will provide some information, including:

  • id: internal Test Id
  • key: Test's issue key
  • summary: Test's summary
  • assignee: Test's issue assignee
  • rank: rank of the Test in the parent folder ("1" corresponds to the first element)
  • workflowStatus: Test's workflow status
  • labels: array of all Test's assigned labels
  • components: array of all Test's assigned components
  • testType: Test type (e.g. "Manual", "Cucumber, "Generic")


Output example for listing only the direct descendants of a given folder
{
 "tests": [
   {
    "id": 24300, 
    "key": "FP-10",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 1,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    "id": 24301,
    "key": "FP-11",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 2,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    ...
   }
  ],
  "total": 3,
}
Output example for listing all descendants of a given folder
{
 "tests": [
   {
    "id": 24300,
    "key": "FP-10",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 1,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    "id": 24301,
    "key": "FP-11",
    "summary": "Issue test create inside folder",
    "assignee": "",
    "rank": 1,
    "workflowStatus": "Open",
    "labels": [],
    "components": [],
    "testType": "Manual",
   },
   {
    ...
   }
  ],
  "total": 3,
}

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500  INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the tests.

 PUT /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests

Add/remove tests to/from the given Test Repository folder. Returns error messages, if there are any.

Request

PATH PARAMETERS
parametertypedescription
projectKeyString

project key

folderIdintegerinternal folder Id
Example
Example Input
{
 "add": [
    "CALC-33",
    "CALC-75"
  ],
  "remove": [
    "CALC-25",
    "CALC-45"
  ]
}

Request example

curl -H "Content-Type: application/json" -X PUT -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/9/tests


Responses

200 OK : text/plain : Successful. Return error messages, if there are any.

Example Output
["Issue with key CALC-33 not found or is not of type Test."]

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray for JIRA license is not valid.

500  INTERNAL SERVER ERROR : text/plain : An internal error occurred associating the tests.

Folders

  • To obtain or update information about a given Test Repository folder, you need to specify both the project key and the internal folder Id
  • To remove a folder from the Test Repository,  you need to specify both the project key and the internal folder Id


 GET /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>

Returns a JSON object with folder information.

Request

PATH PARAMETERS
parametertypedescription
projectKeyString

project key

folderIdintegerinternal folder Id

Request example

curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6

Responses

200 OK : application/json : Successful. Returns a JSON object.

Output example
{
  "id": 6,
  "rank": 1,
  "name": "Folder1",
  "testRepositoryPath": "/Folder1"
  "testCount": 0,
  "totalTestCount": 0
}


400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500  INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.

 POST /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>

Creates a folder and returns a JSON object with folder information.

Request

PATH PARAMETERS
parametertypedescription
projectKeyString

project key

folderIdintegerinternal folder Id; "-1" corresponds to the root folder of the Test Repository


JSON body attributes
parametertypedescription
nameString

name of folder

Example
Input example
{
  "name": "Folder1"
}

Request example

curl -H "Content-Type: application/json" -X POST -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/-1


Responses

201 CREATED : application/json : Successful. Returns a JSON object.

Output example
{
  "id": 6,
  "rank": 1,
  "name": "Folder1",
  "testRepositoryPath": "/Folder1"
  "testCount": 0,
  "totalTestCount": 0
}


400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray for JIRA license is not valid.

500  INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.

 PUT /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>

Updates an existing folder.

Request

PATH PARAMETERS
parametertypedescription
projectKeyString

project key

folderIdintegerinternal folder Id
JSON body attributes
parametertypedescription
nameString

name of folder

rankIntegerrank within the parent folder

Example
Example Input
{
  "name": "Folder1",
  "rank": 4
}

Request example

curl -H "Content-Type: application/json" -X PUT -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6


Responses

204 No content : text/plain : Successful. Does not return anything.

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500  INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.

 DELETE /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>

Remove folder from the Test Repository.

Request

PATH PARAMETERS
parametertypedescription
projectKeyString

project key

folderIdintegerinternal folder Id

Example Request

curl -H "Content-Type: application/json" -X DELETE -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6
Responses

204 No content : text/plain : Successful.

400 BAD_REQUEST : text/plain : Returns the error.

401 UNAUTHORIZED : text/plain : The Xray license is not valid.

500  INTERNAL SERVER ERROR : text/plain : An internal error occurred removing the test.

  • No labels