How to use JIRA-REST API

Some years ago I implemented a git hook to manage JIRA Tickets. I used the JIRA SOAP-API.

Since October 2010 JIRA offers a REST API to handle tickets, but it already had alpha and beta labels until JIRA 5.0. So I decided first to use JIRA SOAP and switch later to JIRA REST. Some weeks ago it was time to change from SOAP to REST.

Requirements

To get a comfortable feeling, I use jira-python. This library eases the use of the JIRA REST API from Python applications. With this API you don’t have to handle the REST-Calls on your own.

Other required packages at a Ubuntu/Debian machine:

  • python 2.X or later (I’ve tested it with Python 2.7.4)
  • JIRA installation with Remote APIs enabled. You can find a short Tutorial how to enable Remote API on the JIRA Documentation
  • Git Version 1.6.X or later (I’ve tested it with Git 1.8.1.2). You can install it from source or from package: sudo apt-get install git git-core
  • Linux or some other similar Unix flavor (I have tested with Ubuntu 12.03 LTS).

Installation fo jira-python

The easiest (and best) way to install jira-python is through pip:

pip install jira-python

It will handle the library/client itself and all necessary requirements.

Usage in git-hook

First of all import the JIRA API:

from jira.client import JIRA

After that you can establish a connection to your JIRA URL. I use a seperate function to connect to JIRA:

def connect_to_jira():
   jira_options = { 'server': JIRA_URL}

   try:
       jira = JIRA(options=jira_options, basic_auth=(USERNAME, PASSWORD))
   except Exception as e:
       jira = None

   return jira

JIRA_URL is your Url, e.g.: https://chiemseesurfer.atlassian.net.

Authentication

The JIRA REST API provides two different authentication methods. HTTP BASIC pass a tuple of (username, password) to the basic_auth constructor argument like seen above. OAuth pass a dict of OAuth properties to the oauth constructor argument. A detailed description how to use OAuth can be found at jira-python documentation.

Modify/Ask JIRA Issue

It is also possible to get the status of a JIRA Issue. If we want to check if an issue is fixed, we can handle it like the following line:

if str(jira.issue(issuekey).fields.status) == JIRA_FIXED:

JIRA_FIXED is your fixed ID. In my case it is Done. In this way you can also change the status of an issue.

All available actions are available at the jira-python documentation

Get sources

The complete Git-hook can be found at github.

comments powered by Disqus