Documentation

REST APIs

Atlassian products have a rich set of REST APIs for you to use. These APIs are the way that you interact with the Atlassian application's features and data.

API Structure

Atlassian's REST APIs follow an established structure. Note that the context-path element is not always used.

https://myhost.com:port/context-path/rest/api-name/api-version/resource-name

Product APIs

Check out the REST API documentation available for JIRA and Confluence for the full range of available REST API calls you can make. Also be sure to compare this with the Product API Scopes to see what scopes your add-on requires for a particular REST API call.

Atlassian Connect

Atlassian Connect provides a set of REST APIs specifically designed for use by add-ons. The api-name used is atlassian-connect.

Index

  • /rest/atlassian-connect/1/addons/{addonKey} [GET]
  • /rest/atlassian-connect/1/addons/{addonKey}/properties [GET]
  • /rest/atlassian-connect/1/addons/{addonKey}/properties/{propertyKey} [GET, PUT, DELETE]

Resources

GET .../addons/{addonKey}

Returns a representation of the add-on with the given key, including the state and license of the add-on.

Parameters:

Location Name Type Description
Path addonKey string

The key of the add-on, as defined in its descriptor

Response fields:

The fields key and version correspond to fields with the same name in the the add-on descriptor.

Name Type Description
state string

The state of the add-on, ENABLED or DISABLED.

host.product string

The display name of the host product, JIRA or Confluence.

host.contacts.name string

The name of a contact person for the host instance.

host.contacts.email string

The e-mail of a contact person for the host instance.

license.active boolean

The state of the license, true for active subscriptions and evaluations, false for terminated subscriptions and expired evaluations.

license.type string

The license type, see FAQ. Possible values include, but are not limited to COMMERCIAL, COMMUNITY, ACADEMIC and DEVELOPER.

license.evaluation boolean

A flag indicating whether the add-on is being used under an evaluation license.

license.supportEntitlementNumber (optional) string

The Support Entitlement Number (SEN) associated with the license. This attribute will be included for a licensed (paid) add-on.

Response representations:

200 - application/json

Request issued by enabled, licensed add-on.

200 - application/json

Request issued by enabled, unlicensed add-on.

200 - application/json

Request issued by disabled add-on.

401 - application/json

Request without credentials or with invalid credentials. Note that this specific resource accepts also requests from disabled add-ons.

403 - application/json

Request issued by an add-on to the resource related with a different add-on.

GET .../addons/{addonKey}/properties

Returns a list of property keys for the given add-on key.

Parameters:

Location Name Type Description
Path addonKey string

The key of the add-on, as defined in its descriptor

Response representations:

200 - application/json
401 - application/json

Request without credentials or with invalid credentials, e.g. by an uninstalled add-on.

404 - application/json

Request issued by a user with insufficient credentials, e.g. for an add-on's data by anyone but the add-on itself, or for a plugin that does not exist.

GET .../addons/{addonKey}/properties/{propertyKey}

Returns a property for the given property key.

Parameters:

Location Name Type Description
Path addonKey string

The key of the add-on, as defined in its descriptor

Path propertyKey string

The key of the property

Query jsonValue boolean

Set to 'true' to have the 'value' field return as a json object. If false it will return the 'value' field as a string containing escaped json. This will be deprecated during June 2016 and the behaviour will default to true.

Response representations:

200 - application/json
400 - application/json

Property key longer than 127 characters.

401 - application/json

Request without credentials or with invalid credentials, e.g. by an uninstalled add-on.

404 - application/json

Request to get a property that does not exist.

404 - application/json

Request issued by a user with insufficient credentials, e.g. for an add-on's data by anyone but the add-on itself, or for a plugin that does not exist.

PUT .../addons/{addonKey}/properties/{propertyKey}

Creates or updates a property.

Parameters:

Location Name Type Description
Path addonKey string

The key of the add-on, as defined in its descriptor

Path propertyKey string

The key of the property

Response representations:

200 - application/json

Property updated.

201 - application/json

Property created.

400 - application/json

Property key longer than 127 characters.

400 - application/json

Request made with invalid JSON.

401 - application/json

Request without credentials or with invalid credentials, e.g. by an uninstalled add-on.

404 - application/json

Request to get a property that does not exist.

404 - application/json

Request issued by a user with insufficient credentials, e.g. for an add-on's data by anyone but the add-on itself, or for a plugin that does not exist.

DELETE .../addons/{addonKey}/properties/{propertyKey}

Deletes a property.

Parameters:

Location Name Type Description
Path addonKey string

The key of the add-on, as defined in its descriptor

Path propertyKey string

The key of the property

Response representations:

204 - application/json

Property deleted.

400 - application/json

Property key longer than 127 characters.

401 - application/json

Request without credentials or with invalid credentials, e.g. by an uninstalled add-on.

404 - application/json

Request to get a property that does not exist.

404 - application/json

Request issued by a user with insufficient credentials, e.g. for an add-on's data by anyone but the add-on itself, or for a plugin that does not exist.