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.

Anchor

	top
	top

`/structure/ GET`	list structures
`/structure/ POST`	create a structure
`/structure/{id} GET`	read structure
`/structure/{id}/update POST`	update one or several structure fields
`/structure/{id} DELETE`	delete structure

Quick navigation:

Anchor

	structureRepresentations
	structureRepresentations

...

Code Block

	javascript
	javascript

{
  "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"
}

Top

Anchor

	structureFields
	structureFields

...

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.

Top

Anchor

	permissionRules
	permissionRules

...

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.

Top

Anchor

	errorEntityRepresentations
	errorEntityRepresentations

...

`code`	Integer code of the error
`error`	Brief technical description of the error. Contains a name of the corresponding StructureError enum constant.
`structureId`	The ID of the structure involved.
`issueId`	The ID of the JIRA issue involved.
`message`	More detailed message, may contain technical details.
`localizedMessage`	User-displayable message in the REST API user locale or JIRA default locale if the user is not authenticated.

Top

Structure Resources

Anchor

	GET_structure
	GET_structure

...

Code Block

	perl
	perl

GET $baseUrl/rest/structure/12.0/structure?permission=edit&withPermissions=true&withOwner=true

...

Code Block

	perl
	perl

GET $baseUrl/rest/structure/12.0/structure.xml?name=test+plan

...

`400 Bad Request`	`permission` parameter is set to an unknown value, or request is invalid for other reasons. In the first case, response contains error entity, in the second it is empty.	`application/json`, `application/xml`
`403 Forbidden`	If Structure Plugin is not accessible to the REST API user, or if issue with ID `issueId` does not exist or the REST API user does not have enough permissions to access it. Response contains error entity.	`application/json`, `application/xml`
`404 Not Found`	If `issueId` is not an integer. Response entity contains a standard JIRA error HTML page.	`text/html`
`500 Internal Server Error`	If an internal error has occurred while processing this request.
`503 Service Unavailable`	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.

Top

Anchor

	POST_structure
	POST_structure

...

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.

...

`400 Bad Request`	Structure data is not well-formed (syntax error) or invalid (semantic error.) Not well-formed structure data examples: request JSON is syntactically incorrect; JSON contains unknown field; `name` is not present or empty; `permissions` list contains a set rule with `level` set to an invalid value. Invalid structure example: `permissions` list contains a rule that fails validation. Response entity contains error. Problems with apply rule usually have `structureId` to indicate the invalid reference.	`application/json`, `application/xml`
`403 Forbidden`	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.	`application/json`, `application/xml`
`500 Internal Server Error`	If an internal error has occurred while processing this request.
`503 Service Unavailable`	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.

Top

Anchor

	GET_structure_id
	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.

...

`400 Bad Request`	One of the query parameters is too long.
`403 Forbidden`	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.	`application/json`, `application/xml`
`404 Not Found`	If `id` is not an integer in `1..2^63-1`. Response entity contains a standard JIRA error HTML page.	`text/html`
`500 Internal Server Error`	If an internal error has occurred while processing this request.
`503 Service Unavailable`	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.

Top

Anchor

	POST_structure_id_update
	POST_structure_id_update

...

Code Block

	perl
	perl

POST $baseUrl/rest/structure/12.0/structure/$id/update

Update one or several fields of a structure by POSTing to this resource.

...

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.

...

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.

...

Code Block

	perl
	perl

POST $baseUrl/rest/structure/12.0/structure/1/update

Request entity

Response entity

Code Block

	javascript
	javascript

{
  "description":"Company-wide structure providing the Big Picture."
}

Code Block

	javascript
	javascript

{
  "id":1,
  "name":"Global Structure",
  "description":"Company-wide structure providing the Big Picture.",
  "editRequiresParentIssuePermission":true,
  "permissions":[
    {
      "rule":"set",
      "subject":"anyone",
      "level":"view"
    },
    {
      "rule":"set",
      "subject":"group",
      "groupId":"jira-users",
      "level":"edit"
    },
    {
      "rule":"set",
      "subject":"group",
      "groupId":"jira-administrators",
      "level":"admin"
    }
  ]
}

...

Code Block

	perl
	perl

POST $baseUrl/rest/structure/12.0/structure

Request entity

Response entity

Code Block

	javascript
	javascript

{
  "permissions":[
    {
      "rule":"set",
      "subject":"group",
      "groupId":"jira-users",
      "level":"edit"
    },
    {
      "rule":"apply",
      "structureId":101
    }
  ]
}

Code Block

	javascript
	javascript

{
  "id": 105,
  "name": "Structure with some permissions",
  "description": "",
  "editRequiresParentIssuePermission": true,
  "permissions": [
    {
      "rule": "set",
      "subject": "group",
      "groupId": "jira-users",
      "level": "edit"
    },
    {
      "rule": "apply",
      "structureId": 101
    }
  ],
  "owner": "user:admin"
}

...

`400 Bad Request`	Structure data is not well-formed (syntax error) or invalid (semantic error.) Not well-formed structure data examples: request JSON is syntactically incorrect; JSON contains unknown field; `permissions` list contains a set rule with `level` set to an invalid value. Invalid structure example: `permissions` list contains a rule that fails validation. Response entity contains error. Responses to problems with an apply rule usually have `structureId` to indicate the invalid reference.	`application/json`, `application/xml`.
`403 Forbidden`	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.	`application/json`, `application/xml`
`500 Internal Server Error`	If an internal error has occurred while processing this request.
`503 Service Unavailable`	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.

Top

Anchor

	DELETE_structure_id
	DELETE_structure_id

...

Code Block

	perl
	perl

DELETE $baseUrl/rest/structure/12.0/structure/108

Code Block

	javascript
	javascript

{
  "empty": true
}

...

`403 Forbidden`	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.	`application/json`, `application/xml`
`404 Not Found`	If `id` is not an integer in `1..2^63-1`. Response entity contains a standard JIRA error HTML page.	`text/html`
`404 Not Found`	If `id` is an integer in `1..2^63-1`, but the structure with the specified `id` does not exist or the user does not have View access level to it.	`application/json`, `application/xml`
`500 Internal Server Error`	If an internal error has occurred while processing this request.
`503 Service Unavailable`	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.

Top

Versions Compared

Old Version 2

New Version 3

Key

Structure Resources

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

Structure Resources