Tag: Rija

Rija Development: Using OAuth Tokens to Make REST API Calls

In my last Rija development post I talked about getting an OAuth access token for Jira so other people can use Rija. This post covers using the access token to make calls to Jira’s REST API. You must perform the following tasks to make API calls with an OAuth token:

  • Get the user’s Jira cloud ID
  • Get the URL for Jira’s REST APIs
  • Add the access token to the authorization header

Get User’s Cloud ID

Each Jira site has a unique cloud ID. You can’t make calls to Jira’s REST API with an OAuth token without the cloud ID for the user’s Jira site. The first thing you must do is get the cloud ID. To get the cloud ID, make a URL request to the following URL:

Add the access token string to the authorization header. Run a URL session with the URL request. The following code retrieves a Jira cloud ID:

JiraCloudID is a struct I created with the properties id, name, and url. The id property contains the cloud ID.


Jira has a different URL for making API calls with an OAuth access token than they have for making calls with a personal access token. The base URL is the following:

Append the cloud ID and the path to the REST API call you’re making.

Add the Access Token to the Authorization Header

I showed the code to add the access token in the code to retrieve the cloud ID. But let’s show it again.

Jira’s REST API requires the string Bearer followed by the access token string. Add the string to the URL request’s authorization header.

If you read Apple’s documentation for the URLRequest class, they tell you not to set the Authorization header manually because it’s a reserved header. But Apple provides no alternative to manually setting the header manually so I have to set the Authorization header manually.

An Example API Call

The following code fetches someone’s Jira projects:

I start by building the URL. I want to sort the projects alphabetically so I supply a URL query item. Then I add the access token to the authorization header. Finally I run the URL request.

Jira’s REST API returns the projects in a dictionary instead of an array. I have to create a JiraProjectList struct to decode the JSON properly. All the struct contains is an array of projects.

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

Rija Development: OAuth Authorization

Authorization Flow

When someone launches Rija for the first time, Rija must get a Jira access token that gives the app access to the person’s Jira account. This involves the following steps:

  1. Show a login view with a button to sign in to Jira.
  2. When the person clicks the button, a private browser opens.
  3. The person signs in to their Jira account.
  4. The person grants Rija permission to access their Jira account.
  5. Jira gives Rija an authorization code.
  6. Rija exchanges the authorization code for the access token.
  7. Rija saves the access token in the Keychain.

This post is going to focus on Steps 3–6.

Sign in to Jira with ASWebAuthenticationSession

The ASWebAuthenticationSession class simplifies logging into websites from Swift apps. To create a login session, create a ASWebAuthenticationSession object and supply three arguments:

  • An authorization URL
  • A callback URL
  • A callback closure

When the login session finishes successfully, the code in the callback closure runs.

Authorization URL

The authorization URL is the URL for the website where you’re logging in. Jira has the following URL for OAuth authorization:

I use the following code to set the URL to sign in to Jira:

Jira’s authorization URL is complex, as you can see by the amount of code needed to build the URL.

Callback URL

The callback URL is where you go when the login session finishes. For iOS and Mac apps the callback URL should take you back to the app.

Creating a callback URL requires you to add a custom URL type to your Info.plist file.


Enter the URL type in the URL Schemes text field. It should look like the following:

But when you supply the callback URL for the login session, you should omit the :// part of the URL. ASWebAuthenticationSession cannot handle colons in the callback URL.

The ASWebAuthenticationSession Code

Using Apple’s ASWebAuthenticationSession class simplifies signing in to websites. The following code initializes and starts the login session:

The following article has more details on login sessions:

Log in to Websites with ASWebAuthenticationSession

Exchange the Authorization Code for the Access Token

After getting the authorization code from Jira, you have to exchange the code for an access token, which you use to make REST API calls in Jira. The exchange involves making a POST request to Jira, supplying the authorization code as part of the body. The following code demonstrates how to exchange the authorization code for an access token:

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

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.

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.

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

Rija Development: Intro

I have started developing Rija, a native Mac (and possibly iOS) app for tracking issues in Jira. I’m experimenting with developing in the open. While I was creating a Twitter thread on developing Rija, I realized there are technical details that might interest other developers that won’t fit a tweet.

This post is the first in a series of posts detailing Rija’s development journey. Future posts are going to be more technical than this one.

Why am I Making Rija?

I used Bee, a Mac issue tracking app that worked with Jira and GitHub issues. The developer stopped developing Bee. I remember some people were upset about the news. I didn’t think much about it and moved on to doing issue tracking online and using text files on my Mac.

Then I saw Atlassian announced they were stopping development of their Mac Jira app. People were disappointed to hear this news.

After doing some more research I learned people hated using Jira’s website. The website is slow and uses lots of RAM. The website does not support Dark Mode. I saw numerous complaints about the difficulty of figuring out how to do things on Jira’s website.

I realized I could help people by making a native Mac app for Jira. A native app would be faster than the website and use less RAM. A native app supports both Light and Dark modes. Developers wouldn’t need to have a browser tab open for hours at a time and wouldn’t have to worry about mistakenly closing the tab. Issue tracking is the area where developers spend the most time on Jira so I should focus on that first.

Rija’s Technology Stack

I’m using SwiftUI to make Jira. By using SwiftUI I can make Rija run on both Mac and iOS. I’m focusing on the Mac version first because Atlassian stopped making a Mac app and continue to develop an iOS app for Jira.

Rija’s Current Development Status

Rija is in the very early stages of development. I wanted to know if I could work with Jira’s REST APIs in a Mac app. I was able to get a list of projects, a list of issues for a project, and show an issue’s summary and details using my Jira account.

The next step in Rija’s development is to get the app to work for anyone with a Jira account. That’s what I’m working on right now.

If you are interested in trying Rija when it’s ready for me to show to other people, go to the Rija page and sign up for the newsletter using the form in the sidebar.