Embedded Files
Â
This tutorial describes how to set up an initial REST API for the Atlassian developer platform, and how to deploy this API to Google Cloud.
We will use Node.js and the Express framework for the API. If you don't already have Node.js on your computer, go to this page to do the installation: Download | Node.js (nodejs.org).Â
Let's start setting up two files that are required for an initial API on an index (root) page.Â
server.js file:
const express = require('express');
const app = express();
const path = require('path');
// index page
app.get("/", (req, res) => {
res.send("This is the MoJira API");
});
// Listen to the App Engine-specified port, or 8080 otherwise
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
console.log(`Server listening on port ${PORT}...`);
});
package.json file:
{
"name": "mojira-api",
"version": "1.0.0",
"description": "",
"main": "server.js",
"scripts": {
"start": "node server.js",
"build": "node server.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "xke",
"dependencies": {
"express": "^4.18.2"
}
}
The above two files have the necessary code for an API server on either the local computer (localhost) or in a Cloud environment (e.g. Google App Engine).
On our local computer, we can open a command-line (terminal) window and run the code using the commands "npm install" and "npm start".Â
Once the server is running on the local computer, we can go to a browser window and see the "This is the MoJira API" message.
Deploying an initial API on Google Cloud
To deploy this initial API on Google Cloud, we need to have a Google Cloud account and also download the Google Cloud Command-Line Interface (CLI). These links provide the instructions to follow for the required Google Cloud tools:
Once you have a Google Cloud account, use the Google Cloud console to create a new project. Our project is called "mojira-api" (you will need to choose a different project name).
To successfully deploy to Google Cloud's App Engine service, we need a new "app.yaml" file that specifies the Node.js version we want to use. Any recent version of Node.js is okay. Below example file uses "nodejs20".
app.yaml file:
runtime: nodejs20
We're then able to use Google Cloud CLI commands to deploy the API on App Engine.Â
"gcloud auth login" to login to your Google Cloud account
"gcloud config set project PROJECT_ID" to specify the Google Cloud project to use
"gcloud app deploy" to deploy the Node.js code to Google Cloud App Engine
We deployed our app to the us-central region, but you can choose a different region
Below screenshot shows the commands in context.
Since we've deployed our app to mojira-api.uc.r.appspot.com, going to that URL shows the initial API message.
Now that we know how to run a basic API on both our local computer and on the Cloud, let's continue with setting up an API that accesses the Atlassian Jira REST API.
Below is the API method that we add to server.js:
// API: Output JSON of Jira issues based on Subdomain and Project Key
// ------------------------------------------------------------------
app.get('/get-issues-from-project', async function (req, res) {
subdomain = req.query.subdomain;
project = req.query.project;
if(subdomain == undefined || project == undefined) {
// defaults
subdomain = "ecosystem";
project = "FRGE";
}
jqlString = `project = ${project} ORDER BY votes DESC`;
fieldsString = 'key, summary, description, assignee, reporter, issuetype, priority, status, votes'
urlString = 'https://'+subdomain+'.atlassian.net/rest/api/3/search?jql='+encodeURIComponent(jqlString)+'&fields='+encodeURIComponent(fieldsString);
authString = process.env.AUTH_EMAIL + ":" + process.env.AUTH_TOKEN;
fetch(urlString, {
method: 'GET',
headers: {
'Authorization': `Basic ${Buffer.from(authString).toString('base64')}`,
'Accept': 'application/json'
}
})
.then(response => {
return response.text();
})
.then(text => {
jsonArrayObj = JSON.parse(text)
res.json(getJsonOutputList(jsonArrayObj));
})
.catch(err => console.error(err));
});
We also make use of a utility method to parse and display the JSON output:
// Body parser for API parameters
app.use(express.urlencoded({ extended: true }));
app.set('json spaces', 2)
// utility method to get JSON output of Jira issues
function getJsonOutputList (jsonArrayObj) {
jsonOutputList = []
count = 0
if (jsonArrayObj["issues"].length == undefined) {
return [];
}
for (var i=0; i<jsonArrayObj["issues"].length; i++) {
var issue = jsonArrayObj["issues"][i];
//console.log(JSON.stringify(issue, null, 2));
url = `https://${subdomain}.atlassian.net/browse/${issue['key']}`;
output = {"subdomain": subdomain,
"id": issue['id'],
"key": issue['key'],
"url": url,
"summary": issue['fields']['summary'],
// "description": (issue['fields']['description']) ? issue['fields']['description']['content'] : null,
"assignee_id": (issue['fields']['assignee']) ? issue['fields']['assignee']['accountId'] : null,
"assignee_name": (issue['fields']['assignee']) ? issue['fields']['assignee']['displayName'] : null,
"reporter_id": (issue['fields']['reporter']) ? issue['fields']['reporter']['accountId'] : null,
"reporter_name": (issue['fields']['reporter']) ? issue['fields']['reporter']['displayName'] : null,
"issuetype": issue['fields']['issuetype']['name'],
"priority": issue['fields']['priority']['name'],
"status": issue['fields']['status']['name'],
"votes": issue['fields']['votes']['votes']
}
jsonOutputList.push(output)
count += 1
}
return jsonOutputList;
}
The entirety of the above code is available in the files in this GitHub repository:
https://github.com/xke/mojira-api-tutorial
We use Google Cloud commands to deploy the most recent version of the code e.g. "gcloud app deploy".
After deployment, this API endpoint displays issues from Atlassian's Forge Ecosystem Jira board.
https://mojira-api.uc.r.appspot.com/get-issues-from-project?subdomain=ecosystem&project=FRGE
Below screenshot shows the output of the API endpoint.
Page updated
Report abuse