Document toolboxDocument toolbox

This article is for Data Center. Visit Cloud

Structure REST API Reference

Owned by Jaramy Conners
Last updated: Sept 25, 2024
2 min read

Structure REST API is under development. The functionality available through REST is sometimes not complete, but it allows to work with the structures.

API version 2 is also not stable, although we're not seeing major changes coming to the main resources.

Both version 1 and version 2 of the REST APIs have been driven by the needs of Structure Widget. We're currently developing a higher-level API specifically for integrations rather than for the product itself. Let us know at

Unable to render {include} The included page could not be found.
if you'd like to contribute or get preliminary access to that API.

General Notes

API Versions

As of Structure version 3.4, there are two versions of the REST API – 1.0 and 2.0. Some of the REST resources are exposed through version 1.0 and some through version 2.0.

Version 1.0 is stable and we don't plan to change it. It comes from Structure 2 and largely remains the same as in Structure 2.x versions. Some of the resources may become deprecated as we replace them with the newer versions.

Version 2.0 is not stable and is being developed along with the product. That means that you can use it, but you need to test your integration every time you upgrade. We are also going to publish API changes in the release notes.

REST Resource Addresses

Structure REST API resources have the URL

BASEURL/rest/structure/VERSION/NAME

where BASEURL is the base JIRA address (http://localhost:2990/jira being standard base URL for development environment), VERSION is the version of the API (either 1.0 or 2.0) and NAME is the name of the resource. For each documented resource there's an indication about its API version.

Authentication

Authentication is done via standard JIRA authentication engine and supported by cookies. When accessing REST API from a remote application, you may need to set up the session first by calling JIRA authentication REST resource. (You don't need to do that if you access Structure REST API from a JavaScript on a page from the same JIRA instance.)

Most read operations are available to non-authenticated access (subject to permission checks for the anonymous user). Most mutation operations are available to authenticated users only.

Required headers

Do not forget to add the following header into REST requests:

Accept - application/json
Content-Type - application/json

REST Resources

  • Structure Resource is used to create and manage structures (but not the content)
  • Forest Resource is used to retrieve and update forests (a structure's content)
  • Item Resource is used to create and update items (issues, folders and, possibly, items of other types)
  • Value Resource is used to retrieve attribute values for a given forest
  • Attribute Subscription Resource allows subscribing to a particular set of values identified by attributes and rows, and receive updates
  • Configuration Resource lets you manage global permissions and the list of projects for which Structure is enabled