Tag: Rija

May 23, 2022

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:

https://api.atlassian.com/oauth/token/accessible-resources

1 2	https://api.atlassian.com/oauth/token/accessible-resources

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:

func retrieveCloudID() async -> String {
    // Build the URL    
    var components = URLComponents()
    components.scheme = "https"
    components.host = "api.atlassian.com"
    components.path = "/oauth/token/accessible-resources"
    var request = URLRequest(url: components.url!)
        
    guard let accessToken = getAccessToken() else {
        return ""
    }
        
    // Add the access token to the authorization header
    let authString = String("Bearer \(accessToken)")
    request.addValue(authString, forHTTPHeaderField: "Authorization")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
        
    // Retrieve the cloud ID
    do {
        let (data, error) = try await URLSession.shared.data(
            for: request, delegate: nil)
        let decoder = JSONDecoder()
        let cloudDictionary = try decoder.decode([JiraCloudID].self, 
            from: data)
        return cloudDictionary.first?.id ?? ""
    } catch {
        print(error)
        return ""
    }
}

func retrieveCloudID() async -> String {

// Build the URL

var components = URLComponents()

components.scheme = "https"

components.host = "api.atlassian.com"

components.path = "/oauth/token/accessible-resources"

var request = URLRequest(url: components.url!)

guard let accessToken = getAccessToken() else {

return ""

}

// Add the access token to the authorization header

let authString = String("Bearer \(accessToken)")

request.addValue(authString, forHTTPHeaderField: "Authorization")

request.addValue("application/json", forHTTPHeaderField: "Content-Type")

// Retrieve the cloud ID

do {

let (data, error) = try await URLSession.shared.data(

for: request, delegate: nil)

let decoder = JSONDecoder()

let cloudDictionary = try decoder.decode([JiraCloudID].self,

from: data)

return cloudDictionary.first?.id ?? ""

} catch {

print(error)

return ""

}

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

Get Jira’s REST API URL

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:

https://api.atlassian.com/ex/jira

1 2	https://api.atlassian.com/ex/jira

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.

guard let accessToken = getAccessToken() else {
    return ""
}
        
let authString = String("Bearer \(accessToken)")
request.addValue(authString, forHTTPHeaderField: "Authorization")

guard let accessToken = getAccessToken() else {

return ""

}

let authString = String("Bearer \(accessToken)")

request.addValue(authString, forHTTPHeaderField: "Authorization")

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:

func fetchProjects() async throws -> JiraProjectList {
    let cloudID = await getCloudID()
        
   // Build the URL 
    var components = URLComponents()
    components.scheme = "https"
    components.host = "api.atlassian.com"
    components.path = "/ex/jira/" + cloudID 
            + "/rest/api/3/project/search"
    
    // Sort projects alphabetically by default
    components.queryItems = [
        URLQueryItem(name: "orderBy", value: "name")
    ]
    var request = URLRequest(url: components.url!)
        
    // JiraProjectList contains an array of projects.   
    guard let accessToken = getAccessToken() else {
       return JiraProjectList()
    }
        
    // Add access token to authorization.
    let authString = String("Bearer \(accessToken)")
    request.addValue(authString, forHTTPHeaderField: "Authorization")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
        
    let (data, error) = try await URLSession.shared.data(for: 
        request, delegate: nil)
    let decoder = JSONDecoder()
    return try decoder.decode(JiraProjectList.self, from: data)
}

func fetchProjects() async throws -> JiraProjectList {

let cloudID = await getCloudID()

// Build the URL

var components = URLComponents()

components.scheme = "https"

components.host = "api.atlassian.com"

components.path = "/ex/jira/" + cloudID

+ "/rest/api/3/project/search"

// Sort projects alphabetically by default

components.queryItems = [

URLQueryItem(name: "orderBy", value: "name")

]

var request = URLRequest(url: components.url!)

// JiraProjectList contains an array of projects.

guard let accessToken = getAccessToken() else {

return JiraProjectList()

}

// Add access token to authorization.

let authString = String("Bearer \(accessToken)")

request.addValue(authString, forHTTPHeaderField: "Authorization")

request.addValue("application/json", forHTTPHeaderField: "Content-Type")

let (data, error) = try await URLSession.shared.data(for:

request, delegate: nil)

let decoder = JSONDecoder()

return try decoder.decode(JiraProjectList.self, from: data)

}

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

May 6, 2022

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:

Show a login view with a button to sign in to Jira.
When the person clicks the button, a private browser opens.
The person signs in to their Jira account.
The person grants Rija permission to access their Jira account.
Jira gives Rija an authorization code.
Rija exchanges the authorization code for the access token.
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:

https://auth.atlassian.com/authorize?
  audience=api.atlassian.com&
  client_id=YOUR_CLIENT_ID&
  scope=REQUESTED_SCOPE_ONE%20REQUESTED_SCOPE_TWO&
  redirect_uri=https://YOUR_APP_CALLBACK_URL&
  state=YOUR_USER_BOUND_VALUE&
  response_type=code&
  prompt=consent

https://auth.atlassian.com/authorize?

audience=api.atlassian.com&

client_id=YOUR_CLIENT_ID&

scope=REQUESTED_SCOPE_ONE%20REQUESTED_SCOPE_TWO&

redirect_uri=https://YOUR_APP_CALLBACK_URL&

state=YOUR_USER_BOUND_VALUE&

response_type=code&

prompt=consent

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

var components = URLComponents()
components.scheme = "https"
components.host = "auth.atlassian.com"
components.path = "/authorize"
components.queryItems = [
    URLQueryItem(name: "audience", value: "api.atlassian.com"),
    URLQueryItem(name: "client_id", value: clientID),
    URLQueryItem(name: "scope", value: 
        "read:jira-user 
        read:jira-work 
        manage:jira-configuration 
        manage:jira-project 
        write:jira-work 
        offline_access"),
    URLQueryItem(name: "redirect_uri", value: callbackUrl + "://auth"),
    URLQueryItem(name: "state", value: UUID().uuidString),
    URLQueryItem(name: "response_type", value: "code"),
    URLQueryItem(name: "prompt", value: "consent")
]
        
guard let authURL = components.url else {
    return
}

var components = URLComponents()

components.scheme = "https"

components.host = "auth.atlassian.com"

components.path = "/authorize"

components.queryItems = [

URLQueryItem(name: "audience", value: "api.atlassian.com"),

URLQueryItem(name: "client_id", value: clientID),

URLQueryItem(name: "scope", value:

"read:jira-user

read:jira-work

manage:jira-configuration

manage:jira-project

write:jira-work

offline_access"),

URLQueryItem(name: "redirect_uri", value: callbackUrl + "://auth"),

URLQueryItem(name: "state", value: UUID().uuidString),

URLQueryItem(name: "response_type", value: "code"),

URLQueryItem(name: "prompt", value: "consent")

]

guard let authURL = components.url else {

return

}

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:

appname://

1 2	appname://

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.

let callbackUrl = "rija"

1 2	let callbackUrl = "rija"

The ASWebAuthenticationSession Code

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

var webAuthSession: ASWebAuthenticationSession?

webAuthSession = ASWebAuthenticationSession.init(url: authURL,  callbackURLScheme: callbackUrl, 
    completionHandler: { (callback:URL?, error:Error?) in

    guard error == nil, let successURL = callback else {
        return
    }

    // Get the authorization code.
    let query = URLComponents(string: (successURL.absoluteString))?
        .queryItems?.filter({$0.name == "code"}).first
            
    let authorizationCode = query?.value ?? ""
            
    // Exchange the authorization code for an access token and save it 
    // in the Keychain. I have to make the calls inside the 
    // callback to ensure there's a valid authorization 
    // code before doing anything else.

    // Have to wrap the code in a Task block because 
    // ASWebAuthenticationSession does not 
    // support Swift concurrency (async await).
    Task {
        if let token = await self.exchangeAuthorizationCodeFor
            AccessToken(code: authorizationCode) {
                    
        self.saveTokenInKeychain(token: token)
        }
    }
})

// Run the session
webAuthSession?.presentationContextProvider = self
webAuthSession?.prefersEphemeralWebBrowserSession = true
webAuthSession?.start()

var webAuthSession: ASWebAuthenticationSession?

webAuthSession = ASWebAuthenticationSession.init(url: authURL, callbackURLScheme: callbackUrl,

completionHandler: { (callback:URL?, error:Error?) in

guard error == nil, let successURL = callback else {

return

}

// Get the authorization code.

let query = URLComponents(string: (successURL.absoluteString))?

.queryItems?.filter({$0.name == "code"}).first

let authorizationCode = query?.value ?? ""

// Exchange the authorization code for an access token and save it

// in the Keychain. I have to make the calls inside the

// callback to ensure there's a valid authorization

// code before doing anything else.

// Have to wrap the code in a Task block because

// ASWebAuthenticationSession does not

// support Swift concurrency (async await).

Task {

if let token = await self.exchangeAuthorizationCodeFor

AccessToken(code: authorizationCode) {

self.saveTokenInKeychain(token: token)

}

})

// Run the session

webAuthSession?.presentationContextProvider = self

webAuthSession?.prefersEphemeralWebBrowserSession = true

webAuthSession?.start()

The following article has more details on login sessions:

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:

func exchangeForAccessToken(authorizationCode: String) async -> AuthToken? {
    var components = URLComponents()
    components.scheme = "https"
    components.host = "auth.atlassian.com"
    components.path = "/oauth/token"
        
    var request = URLRequest(url: components.url!)
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
        
    let clientID = ProcessInfo.processInfo.environment["CLIENT_ID"]!
    let clientSecret = ProcessInfo.processInfo.environment["CLIENT_SECRET"]!
        
    request.httpMethod = "POST"
    let body = [
        "grant_type": "authorization_code",
        "client_id": clientID,
        "client_secret": clientSecret,
        "code": authorizationCode,
        "redirect_uri": "rija://auth"
    ]
    let bodyData = try? JSONSerialization.data(withJSONObject: body)
    request.httpBody = bodyData
        
    do {
        let (data, error) = try await URLSession.shared.data(
            for: request, delegate: nil)
        let decoder = JSONDecoder()
            return try decoder.decode(AuthToken.self, from: data)
    } catch {
            print(error.localizedDescription)
    }
        
    return nil
}

func exchangeForAccessToken(authorizationCode: String) async -> AuthToken? {

var components = URLComponents()

components.scheme = "https"

components.host = "auth.atlassian.com"

components.path = "/oauth/token"

var request = URLRequest(url: components.url!)

request.addValue("application/json", forHTTPHeaderField: "Content-Type")

let clientID = ProcessInfo.processInfo.environment["CLIENT_ID"]!

let clientSecret = ProcessInfo.processInfo.environment["CLIENT_SECRET"]!

request.httpMethod = "POST"

let body = [

"grant_type": "authorization_code",

"client_id": clientID,

"client_secret": clientSecret,

"code": authorizationCode,

"redirect_uri": "rija://auth"

]

let bodyData = try? JSONSerialization.data(withJSONObject: body)

request.httpBody = bodyData

do {

let (data, error) = try await URLSession.shared.data(

for: request, delegate: nil)

let decoder = JSONDecoder()

return try decoder.decode(AuthToken.self, from: data)

} catch {

print(error.localizedDescription)

}

return nil

}

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

May 2, 2022

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)
    }
}

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 = &quot;project = &quot; + 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")
]

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

April 25, 2022

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.