A Technical Founder’s Review of APIs — JIRA

As much technical debt as the US has national debt

This is the second review in the series of about 7 APIS. You can find my review of GitHub’s API here. Over the course of the next few weeks, I will be continuing to blog about my experiences with a few APIs I have been using to build OverVue. The focus will mainly be around authentication and webhooks, Ruby and any 3rd party gems used. I will try and keep the reviews light on Ruby code or specific gem usage to make these as general to the API quality as I can. In addition to the JIRA review here, I will also be reviewing Trello’s API, Slack’s, HipChat’s, Bitbucket’s, and Asana’s(I will link out to them as they become complete).

I am using the JIRA API to collect issue creation and update events as well as comment creation to issues via webhooks to coalesce those events with Overvue channels and users. Providing insight into how a team, project or user is doing in correlation to the status and commentary to a report.

The complete experience of integrating with JIRA’s API can be explained in so many words, but to summarize it one…abhorrent. The documentation is all over the place, the API itself is documented in one spot, the confusion on using the long winded OAuth setup or Atlassian Cloud JWT setup, which leads in no way to have a user sign up as simple as most other integrations.

Documentation

I did what most developers do when attempting to start working with an API, Google the integration name and “API”. Which brought me the REST API page. Doesn’t seem so bad…thinking I’ll just checkout the OAuth documentation, and get going. Wrong! You are guided into a long-winded approach of downloading an Atlassian command line tool to install and run JIRA(or other Atlassian projects) locally, in a development environment. I’ll discuss more about this in the Authentication section below.

The prevailing feeling when reading through JIRA and Atlassian documentation around integrating into JIRA is confusion and feeling you’re one link or piece of information away from figuring it out. The problem is that the feeling is never resolved, but replaced with the feeling of “Well, at least it’s working now?”

Getting back to the actual REST API documentation, it seems to be documented fairly well. A list of all endpoints that expand out to each individual endpoint/verb combination. Once one is expanded, you get a preface, and example requests and responses.

Authentication

Oi! With so many stupid simple OAuth processes, by obtaining a developer set of keys and bouncing a series of requests of some OAuth endpoints, JIRA’s processes is so long winded, it’s painful. First, download the Atlassian CLI tool, find the command to spin up JIRA, realize it’s not a cloud version, decide if you need a cloud version for your integration or not, create and SSL key/cert pair, create your own consumer key, then add those to a confusing “Application Link” process, and finally you have a token to make authenticated request. Lastly, don’t forget to record your user’s JIRA domain name, as any API request(or requests through a library) will need to go there, and not a general API URL.

API/Gem

While not using the jira-ruby gem extensively, I have used it for accessing the webhook set up programmatically and basic repo listing. I had previously submitted a pull request that was merged for this functionality as it was missing. However, now the usage was fairly straightforward by providing an authenticated Webhooks object repo information to perform CRUD(Create Read Update Delete) operations. While this gem is stable and working, it seems it has not been kept as up to date as all of the JIRA API changes have been. It can sure use some more open source ❤.

Webhooks

Webhooks play an integral part in OverVue’s event integrations. Setting up webhooks allow the 3rd party services to contact OverVue endpoints to insert events into the database. The events are then sliced and diced into other resources such as channels. JIRA’s webhook API and guides we’re OK. The documentation provided by JIRA was “just enough” information to get going.

In a seemingly separate part of the JIRA/Atlassian docs, you can find the webhook documentation. The guide provides enough information to know how to set up a webhook through the UI or to “do it” through the JIRA API. There was no suggestion to use a URL tunnel service, such as ngrok to get you going during development, which could help a newcomer of integrating webhooks. Additionally, webhooks are not separated by any means in JIRA by default but is suggested you use JQL(JIRA Query Language) to separate in your own way(i.e. “project = *your project key*”). This differs from some other webhook systems which hang off of repos or projects and give you separation by default.

With that being said, one of the highlights on the webhook guide was the payload information. There were links to JSON objects, which were called shapes to show a detailed view of how the webhook payload will look when you receive it. I found this information to be thorough enough for most developers.

Additionally, I have found there was no additional security on webhooks to make sure they are genuine requests from JIRA’s servers OR any way to reply webhooks. Both of these can go a long way in improving the JIRA webhook platform.

API Grade

In the spirit of the series of API reviews I will supply a grade for JIRA as well. Generally, I feel that I don’t want to come off as overly abrasive or cynical, but I was unhappy developing this integration at every turn. I feel like this goes to show that technical debt can be ignored until it is affecting your bottom line, which I doubt it currently is for Atlassian. My grade for the JIRA API is a…

D-

If you like this review or others, please ❤ and recommend! Leave a comment too!