Skip to end of metadata
Go to start of metadata

Available:

JIRA 5.0 and later. REST is the recommended and supported remote API in JIRA 5.0 and later. This is where Atlassian will focus its attention from this point onwards, adding functionality and fixing bugs.

 

JIRA's REST APIs are for developers who want to build functionality on top of JIRA.

Quick links: Tutorials | Reference

On this page:

Overview

The Atlassian REST APIs provide a standard interface for interacting with JIRA and our other applications.

REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE. REST APIs operate over HTTP(s) making it easy to use with any programming language or framework.

The input and output format for the JIRA REST APIs is JSON.

JIRA uses the Atlassian REST plugin to implement the JIRA APIs. The REST plugin is bundled with JIRA. You can add your own REST APIs to JIRA by creating a JIRA plugin that includes the REST plugin module. See the basic principles we employ in our REST API design.

Browsing and Testing your REST APIs from the Application UI

Since the specifics of the REST API vary between Atlassian applications, the best way to learn about the REST API Browser for your product is to use the REST API Browser built into your JIRA instance. 

The REST API Browser lets you browse, inspect and try the REST API Browser for your application. It's a tool for discovering the REST APIs and other remote APIs available in Atlassian applications.

The browser is built into several types of Atlassian applications, including Stash and recent versions of Confluence and JIRA. It's also a part of the Developer Toolbox plugin (included by default in developer instances of Atlassian applications) or available separately.

For details on getting and using the RAB, see Using the REST API Browser

A Simple Example: Creating an Issue in JIRA

Want to create an issue in JIRA via REST? Here's how easy it is.

The examples below use curl. Ideally, you should use the REST API Browser to investigate how the API works, but this example is meant to give you a glimpse.  We'll create an issue in a local JIRA instance.

A few points to note about our example:

  • The input file is denoted by the '--data @filename' syntax. The data is shown separately, and uses the JSON format.
  • Make sure the content type in the request is set to 'application/json', as shown in the example.
  • POST the JSON to your JIRA server. In the example, the server is http://localhost:2990/jira/rest/api/2/issue/.
  • The example uses basic authentication, with a username of admin and password of admin.
  • You'll need to add a project to the instance before running, and get the project ID of the project to which you want to add the issue beforehand.

To try a simple REST command with curl, follow these steps:

  1. Start by creating the data file that contains the POST data. In our command, we'll assume the file is named data.txt. Add the following content:

    Our project ID is 10000. You should use a suitable ID of a project in your instance. Also, the issue type in our case is 3, which represents a task.

    Icon

    Alternatively, find the api/2/issue resource in the REST API Browser, and paste the text above into the Request Body field to try it out.

  2. From the command line enter the following command:

    As before, adjust details for your environment, such as the hostname or port of the JIRA instance. Note that an OnDemand instance or most public instances would require the use of HTTPS and of course valid credentials for the instance.

The response provides the issue ID, issue key, and the URL to the issue (which can then be used to GET additional data, PUT updates, etc).

Instead of using numeric identifiers for the project and issue type, you could have used the key and name of the type instead. For example:

To learn more about creating an issue via REST, see:

Authentication

The REST APIs support basic authentication, OAuth and session authentication. See the examples of basic authentication and OAuth.

The Shape of an Issue in REST

What does an issue look like in JIRA REST? See the JSON for a JIRA Issue in REST.

Issue Fields in REST

How are issue fields handled in REST in JIRA? Here's a guide to the basics.

How to Edit and Update Issues

A guide to how to update an issue via REST.

More Tutorials

See our JIRA REST API tutorials.

Full REST API Documentation

See the details of each REST request and response in our reference documentation.

 

  • No labels

5 Comments

  1. Anonymous

    documentation is incorrect, also signup to this wiki is dis-allowed.

    1. If you'd like to contribute to the documentation: Atlassian Contributor License Agreement

    2. A few glitches in the commands are now fixed, so should no longer be incorrect. But as now advised, your best bet for investigating the API is using the REST API Browser. 

  2. Anonymous

    Does this work for JIRA OnDemand? And if so, how does the authentication work? 

  3. Anonymous

    What's up to the soap api?  Will it be further supported? As far as i know the JIRA connector for mylyn uses soap.