Rija Development: Using Jira’s REST APIs

Developing Rija has me spending a lot of time working with Jira’s REST APIs. This post details some issues I have run into when working with the APIs.

The REST API Wraps Arrays in Dictionaries

In GitHub’s API, if you want to get someone’s repositories or the issues for a given repository, you make the API call, and GitHub gives you an array of repositories or issues.

But Jira’s REST API does not work like GitHub’s. When you make an API call to get a Jira account’s projects, the API returns a dictionary. The array that has the projects is one of the fields in the dictionary.

Wrapping the array inside a dictionary makes decoding the JSON difficult. I kept getting errors saying I was trying to decode an array but the JSON was a dictionary. I had to create new data structures that contained an array of what I what I wanted to get the JSON decoding to work.

struct JiraProjectList: Codable {
  var projects: [Project]
        
  enum CodingKeys: String, CodingKey {
    case projects = "values"
  }
        
  init() {
    projects = []
  }
        
  init(from decoder: Decoder) throws {
    let valueContainer = try decoder.container(keyedBy: CodingKeys.self)
    self.projects = try valueContainer.decode([Project].self, 
      forKey: CodingKeys.projects)
    }
}

You have to Use JQL to Fetch Multiple Issues

Jira’s REST API does not provide a call to get multiple issues. If you want to do something like fetch a list of a project’s issues or the issues assigned to a person, you have to use JQL, Jira’s query language. You have to build a URL string to make a query.

Fortunately the Foundation framework has URLComponents to make building a URL safer. Here’s the code I had to write to set up JQL to retrieve a selected project’s issues.

let projectString = "project = " + project.key
var components = URLComponents()
components.scheme = "https"
components.host = domain + ".atlassian.net"
components.path = "/rest/api/3/search"
components.queryItems = [
  URLQueryItem(name: "jql", value: projectString),
  URLQueryItem(name: "fields", value: "issue,summary,description")
]

Atlassian Document Format

The latest version of Jira’s REST API changed the data type for an issue’s description and its comments. Instead of returning a string, the API returns the description and comments in Atlassian Document Format. Atlassian Document Format is a JSON format that provides support for headings, code blocks, lists, bold text, and italic text.

The problem I ran into is that most of the examples I found on working with issue descriptions and comments used the old API version that returns strings. There aren’t many examples on using Atlassian Document Format.

Early versions of Rija are going to treat everything as a paragraph. Supporting Markdown is a nice to have feature for a future version. Write in Markdown in Rija and have the text in Atlassian Document Format in Jira.

About Rija

Rija is a Jira issue tracker under development for Mac (and possibly iOS). The following article provides more details on Rija:

Rija Development: Intro