This article is for Data Center. Visit Cloud
Structure Resource
- Jaramy Conners
- Su-Lyn Rosenberry
This page describes resources with which you can list, create, read, update, and delete structures. Structures contain general information such as name and permissions, but not the hierarchy itself. Issue hierarchy is accessed through the Forest Resource. This page also documents structure shape and its fields, and the error entity that may be returned in case of the REST API user error.
Structure resource belongs to version 2.0 of the API.
list structures | |
create a structure | |
read structure | |
update one or several structure fields | |
delete structure |
Quick navigation:
Structure Representations
Structure is represented via JSON. All resources are also capable of producing XML.
{
"id": 103,
"name": "Structure with all fields",
"description": "Voilà ! This structure exhibits all fields.",
"readOnly": "true",
"editRequiresParentIssuePermission": true,
"permissions": [
{
"rule": "apply",
"structureId": 102
},
{
"rule": "set",
"subject": "group",
"groupId": "jira-developers",
"level": "edit"
},
{
"rule": "set",
"subject": "projectRole",
"projectId": 10010,
"roleId": 10020,
"level": "admin"
},
{
"rule": "set",
"subject": "anyone",
"level": "view"
},
{
"rule": "set",
"subject": "user",
"username": "agentk",
"level": "none"
}
],
"owner": "user:admin"
}Structure Fields
Structure objects accessible through these resources have the following fields, most of which represent structure details as outlined in the Structure User's Guide:
| The ID of the structure (integer, |
| The name of the structure. A structure must have a non-empty name, which does not have to be unique. |
| The description on the structure. May be absent. |
|
|
|
|
| The list of structure permission rules. Present only if the user has Control access level to the structure. Some resources do not include permissions unless requested to do so. List order is as important as the rules themselves. |
| The owner of the structure. Present only if the user is the owner of this structure or if he has Browse Users permission. A string of the form |
Please note that structure resources described on this page do not include information about issue hierarchies. The content of a structure, i.e. its hierarchy of items, can be read or modified using Forest Resource.
Permission rules
There are two types of permission rules, those that set permissions and those that apply permissions from another structure. They have different fields depending on the type.
Set rules
| Must be equal to |
| Identifies the type of the subject to which the rule applies. Must be one of |
| Access level to set to the specified subject. Must be equal to one of the names of the Permission Level enum constants, case-insensitive. |
In addition, there are fields to identify the subject.
group
The rule applies to all users within the JIRA group.
| The name of the JIRA group. Example: |
REST API user can create such rule only for a group he belongs to.
projectRole
The rule applies to all users that have a role in a project.
| The ID of the project. Example: |
| The ID of the role. Example: |
REST API user can create such rule only for roles in projects where Structure is enabled, and for which he has Browse Projects permission.
user
The rule applies to the user.
| Name of the user. Example: |
REST API user can create such rule only if he has Browse Users permission, and if such user exists.
anyone
The rule applies to all users, even anonymous (not authenticated.) The rule shouldn't have any additional fields.
Apply rules
| Must be equal to |
| The ID of the structure which permissions should be applied. Example: |
Apply rule creates a dependency on another structure. Circular dependencies are not allowed. Also, a REST API user can create such rule only if he has Control access level to the referenced structure.
Error entity
{
"code": 4005,
"error": "STRUCTURE_NOT_EXISTS_OR_NOT_ACCESSIBLE[4005]",
"structureId": 160,
"message": "Referenced structure [160] does not exist or you don't have Control permissions on it.",
"localizedMessage": "Das Struktur [160] existiert nicht oder sie haben keine Kontrolle Berechtigungen."
}In some cases, requests to structure resources result in an error response containing an error entity. Any of its fields may be absent.
| Integer code of the error |
| Brief technical description of the error. Contains a name of the corresponding StructureError enum constant. |
| The ID of the structure involved. |
| The ID of the JIRA issue involved. |
| More detailed message, may contain technical details. |
| User-displayable message in the REST API user locale or JIRA default locale if the user is not authenticated. |
Structure Resources
GET /structure
GET $baseUrl/rest/structure/2.0/structure
GET $baseUrl/rest/structure/2.0/structure?name=$name&permission=$permission&withPermissions=$withPermissions&withOwner=$withOwner&limit=100
A list of all structures visible to the REST API user. Optionally, the result can be filtered by name or user's access level. By default, permission rules and owners are not included, you should use query parameters if you want them to be included.
Who can access this resource
All users who have access to the Structure Plugin. The returned list contains only structures to which the REST API user has at least View access level.
Request
Query parameters:
| If present, the returned list will contain only structures which names contain the specified string (case insensitive). |
| If present, the returned list will contain only structures to which the REST API user has the specified access level. Must be equal to one of the names of the Permission Level enum constants, case-insensitive. NONE is treated in the same way as VIEW. Please note that Control permission is represented by the ADMIN enumeration constant. |
| If |
| If |
archived | If |
| If specified, must be a number. Defines the maximum number of structures to return. |
Each of the filter parameters name, permission, or issueId can be specified only once, otherwise the first is used. Different parameters are combined with AND.
HTTP headers:
| Should be one of |
| Should be one of |
Response
Success
| Response entity contains the only field, |
|
Example 1: all structures
Â
Example 2: only "Test plan"
Â
Example 3: structures that the user can edit with permissions and owners shown
Â
Example 4: require XML representation
Note that the same can be achieved by specifying application/xml in the Accept HTTP header.
Â
Error
|
|
|
| If Structure Plugin is not accessible to the REST API user, or if issue with ID |
|
| If |
|
| If an internal error has occurred while processing this request. | Â |
| If Structure Plugin is stopped at the time of request. For example, the Restore operation may be in progress. | Â |
Other return codes are possible under the normal rules of HTTP communication.
POST /structure
Create an empty structure by POSTing to this resource.
Who can access this resource
Only logged in users who have access to the Structure Plugin and a permission to create structures.
Request
Request entity should contain the new structure. Structure name, name, must be present and non-empty. Fields id, readOnly, and owner are ignored. All rules in permissions are validated according to their respective rule types.
Please note that this resource accepts only JSON structure representation.
HTTP headers:
| Must be |
| Should be one of |
Response
Success
| Response entity contains the created structure with fields, including |
|
Example 1: minimal structure
Â
Request entity | Response entity |
|---|---|
  |   |
Example 2: structure with some permissions
Â
Request entity | Response entity |
|---|---|
  |   |
Error
| Structure data is not well-formed (syntax error) or invalid (semantic error.) |
|
| If REST API user is not logged in or does not have permissions to access Structure Plugin or to create structures. Response contains error entity. |
|
| If an internal error has occurred while processing this request. | Â |
| If Structure Plugin is stopped at the time of request. For example, the Restore operation may be in progress. | Â |
Other return codes are possible under the normal rules of HTTP communication.
GET /structure/{id}
This resource allows to obtain structure details for the particular structure. By default, permissions and owner are not included, use query parameters to include them.
Who can access this resource
All users who have access to the Structure Plugin. To access the particular structure, the user has to have at least View access level.
Request
Path parameter:
| the ID of the structure |
Query parameters:
| If |
| If |
HTTP headers:
| Should be one of |
| Should be one of |
Response
Success
| Response entity contains the created structure along with all of its fields. |
|
Example 1: retrieve structure with ID 100 without permissions and owner
Â
Example 2: permissions and owner are requested to be included, but only owner is shown, because the user has only View access as indicated by readOnly
Â
Example 3: XML representation may be requested in the request URL instead of the Content-Type HTTP header
Â
Error
| One of the query parameters is too long. | Â |
| If REST API user does not have permissions to access Structure Plugin or does not have at least View permission on this structure. Response contains error entity. |
|
| If |
|
| If an internal error has occurred while processing this request. | Â |
| If Structure Plugin is stopped at the time of request. For example, the Restore operation may be in progress. | Â |
Other return codes are possible under the normal rules of HTTP communication.
POST /structure/{id}/update
Update one or several fields of a structure by POSTing to this resource.
Request
Request entity should contain those structure fields that need to be changed. Non-present fields will not be changed (for this user; readOnly may change for other users as a result of changing permissions.) Fields id, readOnly, and owner are ignored.
Please note that permissions field is modified as a whole, so to add a rule, you have to provide the new list of rules in the proper order.
If permissions field is present, all rules are validated according to their respective rule types.
Please note that this resource accepts only JSON structure representation.
HTTP headers:
| Must be |
| Should be one of |
Response
Success
| Response entity contains the updated structure with all fields, including |
|
Example 1: change description of the Global Structure
Â
Request entity | Response entity |
|---|---|
  |   |
Example 2: changing permission rules
Â
Request entity | Response entity |
|---|---|
  |   |
Error
| Structure data is not well-formed (syntax error) or invalid (semantic error.) |
|
| If REST API user is not logged in, does not have permissions to access Structure Plugin, or does not have Control access level to this structure. Response contains error entity. |
|
| If an internal error has occurred while processing this request. | Â |
| If Structure Plugin is stopped at the time of request. For example, the Restore operation may be in progress. | Â |
Other return codes are possible under the normal rules of HTTP communication.
DELETE /structure/{id}
Deletes the designated structure.
Request
Path parameter:
| the ID of the structure |
HTTP headers:
| Must be |
| Should be absent or equal to one of |
Response
Success
| Contains an object with the only field |
|
Note: it should have been 204 No content instead, but there were reports of some browsers (Firefox) incorrectly processing such results, so it's as it is.
Example
Â
Error
| If REST API user is not logged in, does not have permissions to access Structure Plugin, or does not have Control access level to this structure. Response contains error entity. |
|
| If |
|
| If |
|
| If an internal error has occurred while processing this request. | Â |
| If Structure Plugin is stopped at the time of request. For example, the Restore operation may be in progress. | Â |
Other return codes are possible under the normal rules of HTTP communication.