State of the API

In Structure 3 we had to change API in an incompatible way because the underlying architecture of the product had changed. If you have integration with Structure 2, most likely it won't work with the new Structure and some effort is needed to migrate the code.

As of Structure versions 3.0 – 3.1, the new API is not yet finalized and thorough documentation is not yet published. We plan to spend additional effort on making the APIs simple, stable and well-documented and publish the final documentation then.

Until that time, it's possible to use the current non-published API with Structure 3, however:

• There’s no public documentation on it. The sources of the API artifact are published, but they mostly don’t have javadocs yet.
• There will be backwards-incompatible changes while we finalize the API. The concepts and interfaces will stay mostly the same, but some classes may be moved and optimized. This is less likely to impact REST API, although we plan to introduce new REST APIs that would be simpler than the low-level API we have now.
• There will be new interfaces that would make it easier to deal with the new concepts. Right now it may be a little “low-level” and somewhat more complicated than it needs to be.

Although the documentation about the new API is not available, Structure team will be happy to assist you in migrating your code to work with Structure 3.

This article lists some of the most frequently used API calls. If you need to do something that is not covered by this article or have any questions, please write us at

Conceptual Changes

Forests and Rows

In Structure 2, a structure's content was called a  forest . That is still the case, however, the forest now contains  rows  rather than issues. A row has a Row ID – a long integer primary key for the row. Given row ID, you can retrieve information about the item displayed in that row.

The data structure that represents a forest didn't change. Previously a forest was represented by an array of pairs (issueID, depth). Now the forest is represented by an array of pairs (rowID, depth).

Items

Each row has an associated  item – an issue, a folder, a project or any other type of items. In Structure 3, item types are extendable and an add-on may provide additional types of items to Structure. An item is identified by  Item Identity , which consists of:

• Item Type, represented by a complete module key of a JIRA plugin module that provides the item type, and
• Item ID, represented by either a long integer (for example, issue ID for issues) or by a string (a user key for users).

Sometimes item type is omitted; in that case the implied item type is "issue".

Some of the most popular item types are:

Attributes

Attributes are a generalization of a JIRA's issue fields. An attribute is something that can be calculated for an item. For example, an issue has such attributes as "summary", "key", "priority". But purely Structure-related values are also attributes, such as "sequential number", or "aggregate progress", or "sum of story points". The attributes can also be retrieved for any types of items – for a Confluence page (provided by Structure.Pages extension), "summary" would be the title of the page, "labels" would be the labels, and a new attribute "author" would provide the initial author of the page.

Attributes are identified by an attribute specification, or attribute spec. It is usually represented as a JSON object with an ID and parameters.

Concept Comparison

REST API

Retrieving Structure Forest

GET /rest/structure/2.0/forest/latest?s={%22structureId%22:$id} 

This method retrieves a content of a structure. If structure has generators, the generated content is returned. Generators are preserved in the forest.

Parameters:

• $id – structure ID

Return value sample:

{
  "spec":{"structureId":171},
  "formula":"10394:0:4/356,10332:0:14707,10374:1:5/240,10348:2:14717",
  "itemTypes":{
    "4":"com.almworks.jira.structure:type-generator",
    "5":"com.almworks.jira.structure:type-folder"
  },
  "version":{
    "signature":-1659607419,
    "version":1
  }
}

POST /rest/structure/2.0/forest/update

{
  "spec": { "structureId": <id> }, // use structure ID
  "version": { "signature": <signature>, "version": <version> },  // use last seen signature and version
  "actions": [
     {
         "action": "add", 
         "under": 0,        // at the top level
         "after": 123,      // after row ID 123 (not issue iD!)
         "before": 456,   // before row ID 456
         "forest": "-100:0:10001"   // insert issue 10001, -100 is the temporary row ID which will be mapped into the real row ID when the method returns
     },
     {
         "action": "move", // works like previously, only row IDs instead of issue IDs
         "rowId": 123,
         "under": 456,
         "after": 0,
         "before": 124
     },
    {
       "action": "remove",
       "rowId": 442
     }
  ]
}

POST /rest/plugins/structure/2.0/structure

{
   "name": "my structure",
   "description": "my description",
   "permissions": [   ]    // same format you see when you GET structure
} 

 DELETE /rest/plugins/structure/2.0/structure/<id>

AttributeSpecBuilder
  .create(“customfield", ValueFormat.NUMBER)
  .params()
    .set("fieldId", 10000) // 10000 – the id of "Story Points" custom field
    .build()

AttributeSpecBuilder
  .create("sum", ValueFormat.NUMBER)
  .params()
    .setAttribute(storyPoints)   // storyPoints = the attribute spec for Story Points
    .set("distinct", true)       // exclude duplicates
    .build()

forestSource.apply(new UpdatableForestSource.Update.Add(
  CoreIdentities.issue(10200), 1040, 1900, 2000))

forestSource.apply(new UpdatableForestSource.Update.Remove(
  LongArray.create(10100, 10102)))

forestSource.apply(new UpdatableForestSource.Update.Move(
  LongArray.create(1010), 1040, 0, 1060))