Overview

JIRA JavaScript Client API

About

This is an experimental JavaScript API for accessing the JIRA REST services from a variety of runtime contexts. Currently it includes support for execution from within a JIRA page (e.g. loaded by a plugin) or from within a Remote App iframe. Support for other environments, such as foreign pages (via CORS) or on the server side (e.g. running in Rhino and/or Node.js) may be added in the future.

The API here exposes (or reuses) the JIRA global variable. The functions listed in the API section below are children of this global. Each of these functions returns a promise (conforming to the jQuery Deferred object API) for the async operation it invokes (though jQuery is not required for remote apps, as we provide a custom Deferred implementation when needed). To specify the necessary async callbacks for any given operation, use the Deferred object's standard done, fail, or then methods to attach appropriate handlers. For example, one might retrieve an issue by key and print the result to the console as follows:

JIRA.issue("TEST-1")
  .done(function (data, status, xhr) {
    console.log(data status, xhr);
  })
  .fail(function (xhr, status, err) {
    console.error(xhr, status, err);
  })

A helper function is included in the API that makes it easy to experiment with the rest of the API in browser-side developer tooling like Firebug. The function JIRA.trace(true) can be called to automatically add console logging to your invocations so that you need not wireup attach callbacks everytime you invoke one manually on the CLI.

Using

Loaded via a JIRA Plugin

To use from a JIRA plugin, you'll need to set up one of the following scripts as a standard web resource, or load it yourself through some other mechanism:

Development:

dist/jira-client-plugin.js

Production:

dist/jira-client-plugin.min.js

As a Remote App

In addition to loading the required Remote Apps project's all.js runtime library in your remote app, you'll need to download and include one of the following script files in your application, after the all.js script:

Development:

dist/jira-client-remoteapp.js

Production:

dist/jira-client-remoteapp.min.js

Building

To build, clone this repo and run 'cake build' (you also need to have Node.js, CoffeeScript and UglifyJS installed on your system for the build to run).

Troubleshooting

Remote Apps that wish to utilize this API must include certain API scope permissions in their remote app desciptors to enable the use of each of the methods below. If you see a 403 error reponse when invoking any of these APIs, chances are that you have not requested the proper permission(s) in your descriptor.

API Reference

This is a list of all currently implemented functions. Each function signtature is followed by the REST resource that it operates on, for cross-referencing with the official REST API documentation.

Application Properties

applicationProperties({key})
  /application-properties

updateApplicationProperty(id, object)
  /application-properties/{id}

Attachment

attachmentMeta()
  /attachment/meta

attachment(id)
  /attachment/{id}

destroyAttachment(id)
  /attachment/{id}

Component

createComponent(object)
  /component

component(id)
  /component/{id}

updateComponent(id, object)
  /component/{id}

destroyComponent(id, {moveIssuesTo})
  /component/{id}

componentRelatedIssueCounts(id)
  /component/{id}/relatedIssueCounts

Custom Field Option

customFieldOption(id)
  /customFieldOption/{id}

Dashboard

dashboards({filter, startAt, maxResults})
  /dashboard
dashboard(id)
  /dashboard/{id}

Field

field()
  /field

Filter

filterFavourite()
  /filter/favourite

filter(id)
  /filter/{id}

Groups

groupsPicker({query, exclude})
  /groups/picker

Issue

createIssue(object)
  /issue

issueCreateMeta({projectIds, projectKeys, issuetypeIds, issuetypeNames})
  /issue/createmeta

issue(issueIdOrKey, {fields, expand})
  /issue/{issueIdOrKey}

updateIssue(issueIdOrKey, object)
  /issue/{issueIdOrKey}

destroyIssue(issueIdOrKey, {deleteSubtasks})
  /issue/{issueIdOrKey}

updateIssueAssignee(issueIdOrKey, object)
  /issue/{issueIdOrKey}/assignee

issueComments(issueIdOrKey)
  /issue/{issueIdOrKey}/comment

createIssueComment(issueIdOrKey, object)
  /issue/{issueIdOrKey}/comment

issueComment(issueIdOrKey, id)
  /issue/{issueIdOrKey}/comment/{id}

updateIssueComment(issueIdOrKey, id, object)
  /issue/{issueIdOrKey}/comment/{id}

destroyIssueComment(issueIdOrKey, id)
  /issue/{issueIdOrKey}/comment/{id}

issueEditMeta(issueIdOrKey)
  /issue/{issueIdOrKey}/editmeta

issueRemoteLinks(issueIdOrKey, {globalId})
  /issue/{issueIdOrKey}/remotelink

createIssueRemoteLink(issueIdOrKey, object)
  /issue/{issueIdOrKey}/remotelink

issueRemoteLink(issueIdOrKey, linkId)
  /issue/{issueIdOrKey}/remotelink/{linkId}

updateIssueRemoteLink(issueIdOrKey, linkId, object)
  /issue/{issueIdOrKey}/remotelink/{linkId}

destroyIssueRemoteLink(issueIdOrKey, linkId)
  /issue/{issueIdOrKey}/remotelink/{linkId}

createIssueTransitions(issueIdOrKey, object)
  /issue/{issueIdOrKey}/transitions

issueTransitions(issueIdOrKey, {transitionId})
  /issue/{issueIdOrKey}/transitions

createIssueVotes(issueIdOrKey, object)
  /issue/{issueIdOrKey}/votes

issueVotes(issueIdOrKey)
  /issue/{issueIdOrKey}/votes

destroyIssueVotes(issueIdOrKey)
  /issue/{issueIdOrKey}/votes

createIssueWatchers(issueIdOrKey, object)
  /issue/{issueIdOrKey}/watchers

issueWatchers(issueIdOrKey)
  /issue/{issueIdOrKey}/watchers

destroyIssueWatchers(issueIdOrKey, {username})
  /issue/{issueIdOrKey}/watchers

issueWorklogs(issueIdOrKey)
  /issue/{issueIdOrKey}/worklog

createIssueWorklog(issueIdOrKey, object, {adjustEstimate, newEstimate, reduceBy})
  /issue/{issueIdOrKey}/worklog

issueWorklog(issueIdOrKey, id)
  /issue/{issueIdOrKey}/worklog/{id}

updateIssueWorklog(issueIdOrKey, id, object, {adjustEstimate, newEstimate})
  /issue/{issueIdOrKey}/worklog/{id}

destroyIssueWorklog(issueIdOrKey, id, {adjustEstimate, newEstimate, increaseBy})
  /issue/{issueIdOrKey}/worklog/{id}
createIssueLink(object)
  /issueLink

issueLink(linkId)
  /issueLink/{linkId}

destroyIssueLink(linkId)
  /issueLink/{linkId}
issueLinkTypes()
  /issueLinkType

issueLinkType(issueLinkTypeId)
  /issueLinkType/{issueLinkTypeId}

Issue Type

issueTypes()
  /issuetype

issueType(id)
  /issuetype/{id}

My Permissions

myPermissions({projectKey, projectId, issueKey, issueId})
  /mypermissions

Priority

priorities()
  /priority

priority(id)
  /priority/{id}

Project

projects()
  /project

project(key)
  /project/{key}

createProjectAvatar(key, object)
  /project/{key}/avatar

updateProjectAvatar(key, object)
  /project/{key}/avatar

createProjectAvatarTemporary(key, object, {filename, size})
  /project/{key}/avatar/temporary

destroyProjectAvatar(key, id)
  /project/{key}/avatar/{id}

projectAvatars(key)
  /project/{key}/avatars

projectComponents(key)
  /project/{key}/components

projectVersions(key, {expand})
  /project/{key}/versions

projectRoles(key)
  /project/{key}/role

projectRole(key, id)
  /project/{key}/role/{id}

updateProjectRole(key, id, object)
  /project/{key}/role/{id}

destroyProjectRole(key, id)
  /project/{key}/role/{id}

Resolution

resolutions()
  /resolution

resolution(id)
  /resolution/{id}
search({jql, startAt, maxResults, fields, expand})
  /search

Security Level

securityLevel(id)
  /securitylevel/{id}

Server Info

serverInfo()
  /serverinfo

Status

statuses()
  /status

status(idOrName)
  /status/{idOrName}

User

user({username})
  /user

userAssignableMultiProjectSearch({username, projectKeys, startAt, maxResults})
  /user/assignable/multiProjectSearch

userAssignableSearch({username, project, issueKey, startAt, maxResults, actionDescriptorId})
  /user/assignable/search

createUserAvatar(object, {username})
  /user/avatar

updateUserAvatar(object, {username})
  /user/avatar

createUserAvatarTemporary(object, {username, filename, size})
  /user/avatar/temporary

destroyUserAvatar(id, {username})
  /user/avatar/{id}

userAvatars({username})
  /user/avatars

userSearch({username, startAt, maxResults})
  /user/search

userViewIssueSearch({username, issueKey, projectKey, startAt, maxResults})
  /user/viewissue/search

Version

createVersion(object)
  /version

version(id, {expand})
  /version/{id}

updateVersion(id, object)
  /version/{id}

destroyVersion(id, {moveFixIssuesTo, moveAffectedIssuesTo})
  /version/{id}

createVersionMove(id, object)
  /version/{id}/move

versionRelatedIssueCounts(id)
  /version/{id}/relatedIssueCounts

versionUnresolvedIssueCount(id)
  /version/{id}/unresolvedIssueCount

Web Sudo

destroyWebSudo()
  /websudo