JIRA REST API Integration

1. Introduction

In this article, we’ll have a quick look at how to integrate with the JIRA using its REST API.

2. Maven Dependency

The required artifacts can be found in Atlassian’s public Maven repository:

<repository>
    <id>atlassian-public</id>
    <url>https://packages.atlassian.com/maven/repository/public</url>
</repository>

Once the repository is added to the pom.xml, we need to add the below dependencies:

<dependency>
    <groupId>com.atlassian.jira</groupId>
    <artifactId>jira-rest-java-client-core</artifactId>
    <version>4.0.0</version>
</dependency>
<dependency>
    <groupId>com.atlassian.fugue</groupId>
    <artifactId>fugue</artifactId>
    <version>2.6.1</version>
</dependency>

You can refer to Maven Central for the latest versions of core and fugue dependencies.

3. Creating a Jira Client

First, let’s have a look at some basic information that we need to be able to connect to a Jira instance:

• username – is the username of any valid Jira user
• password – is the password of that user
• jiraUrl – is the URL where the Jira instance is hosted

Once we have these details, we can instantiate our Jira Client:

MyJiraClient myJiraClient = new MyJiraClient(
  "user.name", 
  "password", 
  "http://jira.company.com");

The constructor of this class:

public MyJiraClient(String username, String password, String jiraUrl) {
    this.username = username;
    this.password = password;
    this.jiraUrl = jiraUrl;
    this.restClient = getJiraRestClient();
}

The getJiraRestClient() utilizes all the information provided and returns an instance of JiraRestClient. This is the main interface through which we’ll communicate with the Jira REST API:

private JiraRestClient getJiraRestClient() {
    return new AsynchronousJiraRestClientFactory()
      .createWithBasicHttpAuthentication(getJiraUri(), this.username, this.password);
}

Here, we’re using the basic authentication to communicate with the API. However, more sophisticated authentication mechanisms like OAuth are also supported.

The getUri() method simply converts the jiraUrl into an instance of java.net.URI:

private URI getJiraUri() {
    return URI.create(this.jiraUrl);
}

This concludes our infrastructure of creating a custom Jira client. We can now have a look at various ways to interact with the API.

3.1. Create a New Issue

Let’s start by creating a new issue. We will use this newly created issue for all other examples in this article:

public String createIssue(String projectKey, Long issueType, String issueSummary) {
    IssueRestClient issueClient = restClient.getIssueClient();
    IssueInput newIssue = new IssueInputBuilder(
      projectKey, issueType, issueSummary).build();
    return issueClient.createIssue(newIssue).claim().getKey();
}

The projectKey is the unique that defines your project. This is nothing but the prefix that is appended to all of our issues. The next argument, issueType is also project dependent that identifies the type of your issues like “Task” or “Story”. The issueSummary is the title of our issue.

The issue goes as an instance of IssueInput to the rest API. Apart from the inputs that we described, things like assignee, reporter, affected versions, and other metadata can go as an IssueInput.

3.2. Update Issue Description

Each issue in Jira is identified by a unique String like “MYKEY-123“. We need this issue key to interact with the rest API and update the description of the issue:

public void updateIssueDescription(String issueKey, String newDescription) {
    IssueInput input = new IssueInputBuilder()
      .setDescription(newDescription)
      .build();
    restClient.getIssueClient()
      .updateIssue(issueKey, input)
      .claim();
}

Once the description is updated, let’s not read back the updated description:

public Issue getIssue(String issueKey) {
    return restClient.getIssueClient()
      .getIssue(issueKey) 
      .claim();
}

The Issue instance represents an issue identified by the issueKey. We can use this instance to read the description of this issue:

Issue issue = myJiraClient.getIssue(issueKey);
System.out.println(issue.getDescription());

This will print the description of the issue to the console.

3.3. Vote for an Issue

Once we have an instance of Issue obtained, we can use it to perform update/edit actions as well. Let’s vote for the issue:

public void voteForAnIssue(Issue issue) {
    restClient.getIssueClient()
      .vote(issue.getVotesUri())
      .claim();
}

This will add the vote to the issue on behalf of the user whose credentials were used. This can be verified by checking the vote count:

public int getTotalVotesCount(String issueKey) {
    BasicVotes votes = getIssue(issueKey).getVotes();
    return votes == null ? 0 : votes.getVotes();
}

One thing to note here is that we are again fetching a fresh instance of Issue here as we want to get the updated vote count reflected.

3.4. Adding a Comment

We can use the same Issue instance to add a comment on behalf of the user. Like adding a vote, adding a comment is also pretty simple:

public void addComment(Issue issue, String commentBody) {
    restClient.getIssueClient()
      .addComment(issue.getCommentsUri(), Comment.valueOf(commentBody));
}

We used the factory method valueOf() provided by the Comment class to create an instance of a Comment. There are various other factory methods for advanced use cases, such as controlling the visibility of a Comment.

Let’s fetch a fresh instance of the Issue and read all the Comments:

public List<Comment> getAllComments(String issueKey) {
    return StreamSupport.stream(getIssue(issueKey).getComments().spliterator(), false)
      .collect(Collectors.toList());
}

3.5. Delete an Issue

Deleting an issue is also fairly simple. We only need the issue key that identifies the issue:

public void deleteIssue(String issueKey, boolean deleteSubtasks) {
    restClient.getIssueClient()
      .deleteIssue(issueKey, deleteSubtasks)
      .claim();
}

4. Conclusion

In this quick article, we created a simple Java client that integrates with the Jira REST API and performs some of the basic operations.