| Open api | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
{
"openapi": "3.0.1",
"info": {
"title": "R4JC - Requirements Management for Jira Cloud Rest API",
"description": "Rest APIs for R4JC - Requirements Management for Jira Cloud application.",
"version": "1.0"
},
"servers": [
{
"url": "/"
}
],
"paths": {
"/rest/api/1/tree/projects/{projectKey}/items": {
"put": {
"tags": [
"Tree"
],
"summary": "Move existing item(s) in the tree.",
"description": "Move existing tree item(s) and all its children from one parent location to another location in the tree.",
"operationId": "moveItems",
"parameters": [
{
"name": "projectKey",
"in": "path",
"description": "Jira Project Key",
"example": "TEST",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Important for request body parameters:\n- The Object.id, Object.jiraIssueId, or Object.jiraIssueKey is the target location and where the requested Object.items[n] will be moved to. \n\n\n- The Object.items[n].jiraIssueId or Object.items[n].jiraIssueKey are the items that will be moved.\n\n\n- Only one of the identifiers (id, jiraIssueId, or jiraIssueKey) must be provided per Object.\n\n\n- \"id\" is not supported in the Object.items array. It will be ignored when provided.\n\n\n- If an invalid \"position\" is provided, the item will be moved to the last position in the target location.\n\n\n- A maximum of 100 Object.items may be processed per request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateRequestDto"
},
"examples": {
"Move items to the root folder": {
"description": "-1 is the root folder identifier.",
"value": {
"id": -1,
"jiraIssueId": null,
"jiraIssueKey": null,
"items": [
{
"jiraIssueId": 12195,
"jiraIssueKey": null,
"position": 1
},
{
"jiraIssueId": null,
"jiraIssueKey": "TEST-100",
"position": 2
}
]
}
},
"Move items to the another location": {
"value": {
"id": null,
"jiraIssueId": null,
"jiraIssueKey": "TEST-99",
"items": [
{
"jiraIssueId": 12195,
"jiraIssueKey": null,
"position": 1
},
{
"jiraIssueId": null,
"jiraIssueKey": "TEST-100",
"position": 2
}
]
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successfully moved item(s) recursively from the previous location the the target location in tree. Only the moved items are included in the response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateResponseDto"
},
"example": {
"value": {
"values": [
{
"id": 826,
"isFolder": false,
"jiraIssueId": 12195,
"position": 3,
"hasChildren": false,
"path": [
104,
826
]
}
]
}
}
}
}
},
"400": {
"description": "Request validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Multiple identifiers provided": {
"description": "Only one of these parameters must be provided for this object to pass.",
"value": {
"error": "You should specify either Id, Jira Issue Id, or Jira Issue Key only."
}
},
"No identifiers provided": {
"value": {
"error": "Id, Jira Issue Id, or Jira Issue Key must not be blank."
}
},
"Cannot move root folder": {
"value": {
"error": "Root folder cannot be moved."
}
}
}
}
}
},
"401": {
"description": "Authentication failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorJson"
},
"example": "{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"message\": null,\n \"timeStamp\": \"Tue Nov 16 09:53:46 UTC 2021\",\n \"trace\": null\n}"
}
}
},
"403": {
"description": "User has no permission to view project or project is not active in R4J.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"No project permission": {
"value": {
"error": "You don't have permission to view the project."
}
},
"Project not active": {
"value": {
"error": "Project is not active."
}
}
}
}
}
},
"404": {
"description": "Project or issue does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Project not found": {
"value": {
"error": "Could not find project with key TEST."
}
},
"Issue not found": {
"value": {
"error": "An issue with key 'TEST-1' does not exist for field 'key'."
}
}
}
}
}
},
"500": {
"description": "Server has encountered an error it doesn't know how to handle.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
},
"example": "{\n \"error\": \"Unknown error has occurred.\"\n}"
}
}
}
}
},
"post": {
"tags": [
"Tree"
],
"summary": "Add existing Jira issue(s) to the tree.",
"description": "Add existing Jira issue(s) to a specific location in the tree.",
"operationId": "addExistingIssueToTree_1",
"parameters": [
{
"name": "projectKey",
"in": "path",
"description": "Jira Project Key",
"example": "TEST",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Important for request body parameters:\n- The Object.id, Object.jiraIssueId, or Object.jiraIssueKey is the target location and where the requested Object.items[n] will be added to. \n\n\n- The Object.items[n].jiraIssueId or Object.items[n].jiraIssueKey are the items that will be added.\n\n\n- Only one of the identifiers (id, jiraIssueId, or jiraIssueKey) must be provided per Object.\n\n\n- \"id\" is not supported in the Object.items array. It will be ignored when provided.\n\n\n- If an invalid \"position\" is provided, the item will be moved to the last position in the target location.\n\n\n- A maximum of 100 Object.items may be processed per request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateRequestDto"
},
"examples": {
"Add issues to the root folder": {
"description": "-1 is the root folder identifier.",
"value": {
"id": -1,
"jiraIssueId": null,
"jiraIssueKey": null,
"items": [
{
"jiraIssueId": 12195,
"jiraIssueKey": null,
"position": 1
},
{
"jiraIssueId": null,
"jiraIssueKey": "TEST-100",
"position": 2
}
]
}
},
"Add issues to the another location": {
"value": {
"id": null,
"jiraIssueId": null,
"jiraIssueKey": "TEST-99",
"items": [
{
"jiraIssueId": 12195,
"jiraIssueKey": null,
"position": 1
},
{
"jiraIssueId": null,
"jiraIssueKey": "TEST-100",
"position": 2
}
]
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successfully added Jira issue(s) as tree items in the target location specified. Only the added issues are included in the response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"example": [
{
"id": 826,
"isFolder": false,
"jiraIssueId": 12195,
"position": 1,
"hasChildren": false,
"path": [
104,
826
]
}
]
}
}
},
"400": {
"description": "Request validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Multiple identifiers provided": {
"description": "Only one of these parameters must be provided for this object to pass.",
"value": {
"error": "You should specify either Id, Jira Issue Id, or Jira Issue Key only."
}
},
"No identifiers provided": {
"value": {
"error": "Id, Jira Issue Id, or Jira Issue Key must not be blank."
}
},
"Issue(s) already exist in tree": {
"value": {
"error": "Some issues are already in tree."
}
}
}
}
}
},
"401": {
"description": "Authentication failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorJson"
},
"example": "{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"message\": null,\n \"timeStamp\": \"Tue Nov 16 09:53:46 UTC 2021\",\n \"trace\": null\n}"
}
}
},
"403": {
"description": "User has no permission to view project or project is not active in R4J.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"No project permission": {
"value": {
"error": "You don't have permission to view the project."
}
},
"Project not active": {
"value": {
"error": "Project is not active."
}
}
}
}
}
},
"404": {
"description": "Project or issue does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Project not found": {
"value": {
"error": "Could not find project with key TEST."
}
},
"Issue not found": {
"value": {
"error": "An issue with key 'TEST-1' does not exist for field 'key'."
}
}
}
}
}
},
"500": {
"description": "Server has encountered an error it doesn't know how to handle.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
},
"example": "{\n \"error\": \"Unknown error has occurred.\"\n}"
}
}
}
}
},
"delete": {
"tags": [
"Tree"
],
"summary": "Remove existing item(s) from the tree.",
"description": "Remove existing item(s) and all its children from any location in the tree.",
"operationId": "removeItems",
"parameters": [
{
"name": "projectKey",
"in": "path",
"description": "Jira project key",
"required": true,
"schema": {
"type": "string"
},
"example": "TEST"
},
{
"name": "idOrJiraIssueKey",
"in": "query",
"description": "List of tree item id or Jira issue key",
"required": true,
"schema": {
"type": "string"
},
"example": "TEST-100"
}
],
"responses": {
"200": {
"description": "Successfully removed item(s) and their children from the tree. Only the total number of items removed out of the requested ones will be counted in the response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemovedItemsDto"
},
"example": {
"totalItemsRemoved": 10
}
}
}
},
"400": {
"description": "Request validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Max items exceeded": {
"value": {
"error": "Only a maximum of 100 items can be removed per request."
}
},
"Cannot remove root folder": {
"value": {
"error": "Root folder can not be removed."
}
}
}
}
}
},
"401": {
"description": "Authentication failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorJson"
},
"example": "{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"message\": null,\n \"timeStamp\": \"Tue Nov 16 09:53:46 UTC 2021\",\n \"trace\": null\n}"
}
}
},
"403": {
"description": "User has no permission to view project or project is not active in R4J.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"No project permission": {
"value": {
"error": "You don't have permission to view the project."
}
},
"Project not active": {
"value": {
"error": "Project is not active."
}
}
}
}
}
},
"404": {
"description": "Project or issue does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Project not found": {
"value": {
"error": "Could not find project with key TEST."
}
},
"Issue not found": {
"value": {
"error": "An issue with key 'TEST-1' does not exist for field 'key'."
}
}
}
}
}
},
"500": {
"description": "Server has encountered an error it doesn't know how to handle.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
},
"example": "{\n \"error\": \"Unknown error has occurred.\"\n}"
}
}
}
}
}
},
"/rest/api/1/tree/projects/{projectKey}/items/{idOrJiraIssueKey}": {
"get": {
"tags": [
"Tree"
],
"summary": "Get tree item(s).",
"description": "Get the children of the specified tree item id or Jira issue key. You can retrieve the complete tree structure by recursively using this endpoint on items that return 'hasChildren' parameter as true.",
"operationId": "getTreeStructureById",
"parameters": [
{
"name": "projectKey",
"in": "path",
"description": "Jira project key",
"required": true,
"schema": {
"type": "string"
},
"example": "TEST"
},
{
"name": "idOrJiraIssueKey",
"in": "path",
"description": "The tree item id or jira issue key (Use -1 to get from root folder)",
"required": true,
"schema": {
"type": "string"
},
"example": "TEST-100"
},
{
"name": "startAt",
"in": "query",
"description": "Start offset of the resulting items",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "maxResults",
"in": "query",
"description": "Max number of resulting items (Maximum of 100)",
"required": true,
"schema": {
"type": "integer",
"format": "int32",
"default": 50,
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved tree structure of tree item id or issue key provided. Only the immediate children will be included in the response.\n\n_Tip: Use the \"hasChildren\" property to identify which objects must be recursed to get the complete tree structure._",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TreeItemDto"
},
"examples": {
"Structure to recurse": {
"description": "If some of the \"children\" returned has \"hasChildren\" set to true, further retrieval can be done to complete your tree structure data.",
"value": {
"startAt": 0,
"maxResults": 50,
"total": 2,
"isLast": true,
"values": [
{
"id": 625,
"jiraIssueId": 12195,
"position": 78,
"hasChildren": true,
"isFolder": true,
"path": [
546,
625
],
"children": [
{
"id": 951,
"jiraIssueId": 13526,
"parentId": 52654,
"position": 1,
"hasChildren": true,
"isFolder": false,
"path": [
546,
625,
951
]
},
{
"id": 952,
"jiraIssueId": 13526,
"parentId": 52654,
"position": 1,
"hasChildren": false,
"isFolder": false,
"path": [
546,
625,
952
]
}
]
}
]
}
},
"Structure to skip recursion": {
"description": "If all the \"children\" returned has \"hasChildren\" all set to false, there's nothing else in the structure to retrieve.",
"value": {
"startAt": 0,
"maxResults": 50,
"total": 2,
"isLast": true,
"values": [
{
"id": 625,
"jiraIssueId": 12195,
"position": 78,
"hasChildren": true,
"isFolder": true,
"path": [
546,
625
],
"children": [
{
"id": 951,
"jiraIssueId": 13526,
"parentId": 52654,
"position": 1,
"hasChildren": false,
"isFolder": false,
"path": [
546,
625,
951
]
},
{
"id": 952,
"jiraIssueId": 13526,
"parentId": 52654,
"position": 1,
"hasChildren": false,
"isFolder": false,
"path": [
546,
625,
952
]
}
]
}
]
}
},
"Structure with errors in return": {
"description": "Some item(s) may not be returned successfully due to user browse permissions or issue security.",
"value": {
"startAt": 0,
"maxResults": 3,
"total": 100,
"isLast": false,
"values": [
{
"error": "User does not have permission to browse this issue."
},
{
"id": 625,
"jiraIssueId": 12195,
"position": 78,
"hasChildren": true,
"isFolder": true,
"path": [
546,
625
],
"children": [
{
"id": 951,
"jiraIssueId": 13526,
"parentId": 52654,
"position": 1,
"hasChildren": true,
"isFolder": false,
"path": [
546,
625,
951
]
}
]
},
{
"error": "User does not have permission to browse this issue."
}
]
}
}
}
}
}
},
"400": {
"description": "Request validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"example": {
"error": "maxResults should be of type Integer."
}
}
}
},
"401": {
"description": "Authentication failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorJson"
},
"example": "{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"message\": null,\n \"timeStamp\": \"Tue Nov 16 09:53:46 UTC 2021\",\n \"trace\": null\n}"
}
}
},
"403": {
"description": "User has no permission to view project or project is not active in R4J.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"No project permission": {
"value": {
"error": "You don't have permission to view the project."
}
},
"Project not active": {
"value": {
"error": "Project is not active."
}
}
}
}
}
},
"404": {
"description": "Id or Issue Key does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"example": {
"error": "Id or Issue Key does not exist."
}
}
}
},
"500": {
"description": "Server has encountered an error it doesn't know how to handle.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
},
"example": "{\n \"error\": \"Unknown error has occurred.\"\n}"
}
}
}
}
}
},
"/rest/api/1/tree/search": {
"post": {
"tags": [
"Tree"
],
"summary": "Search for existing item(s) in any tree via JQL",
"description": "Search for existing item(s) in any tree based on a valid JQL query provided.",
"operationId": "searchItems",
"parameters": [
{
"name": "startAt",
"in": "query",
"description": "Start offset of the resulting items",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "maxResults",
"in": "query",
"description": "Max number of resulting items (Maximum of 100)",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 50,
"maximum": 100
}
}
],
"requestBody": {
"description": "Important for request body parameters:\n- The Object.treeProjectId and Object.treeProjectKey is the activated R4J project tree you want to search issues from.\n\n\n- If none of the tree project identifiers are provided, all activated R4J project trees will be searched.\n\n\n- If specifying the activated R4J poject tree you want to search, only one of the identifiers (treeProjectId or treeProjectKey) must be provided per Object.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequestDto"
},
"example": {
"treeProjectId": 10000,
"treeProjectKey": "TEST",
"jql": "project = TEST"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successfully searched item(s) based on JQL query provided.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponseDto"
},
"examples": {
"Issue located in one tree": {
"value": {
"startAt": 0,
"maxResults": 50,
"isLast": true,
"values": [
{
"jiraIssueId": 10000,
"items": [
{
"id": 2,
"path": [
1,
2
],
"treeProjectId": 10000,
"isFolder": true,
"position": 1,
"hasChildren": true
}
]
}
]
}
},
"Issue located in multiple trees": {
"value": {
"startAt": 0,
"maxResults": 50,
"isLast": true,
"values": [
{
"jiraIssueId": 10000,
"items": [
{
"id": 22,
"path": [
13,
22
],
"treeProjectId": 10000,
"isFolder": false,
"position": 5,
"hasChildren": true
},
{
"id": 86,
"path": [
82,
28,
62,
86
],
"treeProjectId": 10025,
"isFolder": false,
"position": 15,
"hasChildren": false
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Request validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Multiple identifiers provided": {
"value": {
"error": "You should specify either tree project id or key only."
}
},
"No identifiers provided": {
"value": {
"error": "Tree project id or key must not be empty."
}
},
"JQL is empty": {
"value": {
"error": "JQL must not be empty."
}
},
"Invalid JQL": {
"value": {
"error": "Invalid JQL provided."
}
}
}
}
}
},
"401": {
"description": "Authentication failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorJson"
},
"example": "{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"message\": null,\n \"timeStamp\": \"Tue Nov 16 09:53:46 UTC 2021\",\n \"trace\": null\n}"
}
}
},
"403": {
"description": "User has no permission to view project or project is not active in R4J.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"No project permission": {
"value": {
"error": "You don't have permission to view the project."
}
},
"Project not active": {
"value": {
"error": "Project is not active."
}
}
}
}
}
},
"404": {
"description": "Project does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiErrorMessage"
},
"examples": {
"Project not found": {
"value": {
"error": "Could not find project with key TEST."
}
}
}
}
}
},
"500": {
"description": "Server has encountered an error it doesn't know how to handle.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessage"
},
"example": "{\n \"error\": \"Unknown error has occurred.\"\n}"
}
}
}
}
}
}
},
"components": {
"schemas": {
"UpdateRequestDto": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"isFolder": {
"type": "boolean"
},
"jiraIssueId": {
"type": "integer",
"format": "int64"
},
"jiraIssueKey": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"UpdateResponseDto": {
"type": "object",
"properties": {
"values": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"RemovedItemsDto": {
"type": "object",
"properties": {
"totalItemsRemoved": {
"type": "integer",
"format": "int32"
}
}
},
"SearchRequestDto": {
"type": "object",
"properties": {
"treeProjectId": {
"type": "integer",
"format": "int64"
},
"treeProjectKey": {
"type": "string"
},
"jql": {
"type": "string"
}
}
},
"PaginatedResponseDto": {
"type": "object",
"properties": {
"startAt": {
"type": "integer",
"format": "int32"
},
"maxResults": {
"type": "integer",
"format": "int32"
},
"total": {
"type": "integer",
"format": "int32"
},
"isLast": {
"type": "boolean"
},
"values": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"TreeItemDto": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"isFolder": {
"type": "boolean"
},
"jiraIssueId": {
"type": "integer",
"format": "int64"
},
"jiraIssueKey": {
"type": "string"
},
"parentId": {
"type": "integer",
"format": "int64"
},
"position": {
"type": "integer",
"format": "int64"
},
"hasChildren": {
"type": "boolean"
},
"path": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"treeProjectId": {
"type": "integer",
"format": "int64"
},
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TreeItemDto"
}
},
"error": {
"type": "string"
}
}
},
"ErrorMessage": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"RestApiErrorMessage": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"traceId": {
"type": "string"
}
}
},
"ErrorJson": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"format": "int32"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"timeStamp": {
"type": "string"
},
"trace": {
"type": "string"
}
}
}
}
}
} |
Page Comparison
Manage space
Manage content
Integrations