Type-safe Jira and Confluence API calls for Atlassian Forge

Atlassian provides excellent tutorials for getting started with Forge app development. They enable you to quickly take your first steps and build your first Forge app. Seibert Group has been in the Atlassian Forge ecosystem since its release in 2019, even publishing the first paid Jira Forge app on the Atlassian Marketplace.

After numerous projects helping customers transition to the Atlassian Cloud, we’ve developed a set of tools that are commonly used in our Forge projects and extend beyond the basic tutorials provided by Atlassian.

Some of our development practices have been distilled into publicly available open-source tools. We believe these can be valuable resources for the broader Forge developer community.

This article focuses on our type-safe API client generator, atlassian-ts-client-generator.

The default Forge API request

One common task for Forge developers is working with Atlassian’s REST APIs. When following the standard tutorials for making an API call in Forge, you’ll quickly end up with code that looks like this, assuming you’re using TypeScript:

import api, { route } from "@forge/api";

// this fetches an issue from Jira
const response = await api
  .asUser()
  .requestJira(route`/rest/api/2/issue/TEST-1`);

// issue is not type-safe. The code editor does not know what properties are available on the response.
const issue = response.json();
// this is a mistake that will not be caught by your code editor
const fields = issue.filds;

While this approach works functionally, it lacks type safety, leaving developers without proper IDE assistance and prone to runtime errors when accessing the properties of the issue constant. Imagine you want to access the fields property of the issue. The editor won’t provide autocompletion or type checking, leading to potential errors. For example, if you mistype fields as filds, the IDE won’t catch it, and you’ll only discover the mistake at runtime. This means: You will likely see an exception like TypeError: Cannot read properties of undefined (reading 'filds') when using your app.

Type-safe API clients

To address this, we created atlassian-ts-client-generator. This tool generates TypeScript client code for Atlassian APIs, providing type-safe access to API responses. It allows developers to work with the API in a more structured and type-safe manner, reducing the risk of errors and improving the overall development experience.

Let’s stick with the example of fetching an issue from Jira. Instead of using the default Forge API request, you can use the generated client code to access the same issue in a type-safe way. Accessing an issue from Jira via Forge using atlassian-ts-client-generator looks like this:

import { IssuesApi } from "./atlassian-ts-client-generator/jira-cloud-api";

const issuesApi = new IssuesApi(config);
const issue = await issuesApi.getIssue({
  // more type-safe access to the API
  issueIdOrKey: "TEST-1",
});
// more type-safe access
const fields = issue.fields;

This way, the IDE can provide autocompletion and type checking for the needed API properties (issueIdOrKey in this case) and the response (issue and its fields in this case). This works for all Atlassian APIs, including Jira, Confluence, and Bitbucket. However, it relies on the OpenAPI specifications provided by Atlassian. These specifications are not always up to date.

Seibert’s client generator makes the best use of the available type information and applies patches to known quirks in the OpenAPI specifications. At the very least, it will save you and your team time when working with the APIs, as you usually won’t have to look up the path of a specific API endpoint in the documentation anymore.

Our product teams benefit from this time savings every day. We’ve even migrated existing codebases for Forge apps that have been around for a while (like Awesome Custom Fields) make API access less error-prone. 🚀

How to integrate the library in your Forge app

As always, the answer to this question is: It depends. It is recommended to copy and paste the whole tooling into your repository. Therefore, navigate to GitHub and download the files as a ZIP archive. Unzip the archive and copy the files into a new directory in your Forge app directory.

You can then import the needed files into your application code. The example above we mentioned IssuesApi. But you can also use the other APIs, such as ProjectsApi, IssueTypesApi, and so on. You can find all available APIs different folders in the generated client code.

To use a client you will need to construct a Configuration object. To make a Jira API call from the browser via a Custom UI in Forge you can use the following code:

import { Configuration } from "./atlassian-ts-client-generator/jira-cloud-api";
import { requestJira } from "@forge/bridge";

const config = new Configuration({
  basePath: "",
  fetchApi: requestJira,
});

const issuesApi = new IssuesApi(config);
// continue with your API call as shown above

Note: If you’re using Forge UI Kit or want to make calls asUser or asApp your implementation might look slightly different. Seibert Group is happy to help you with the development of your Forge app and adjust the integration to your needs. 💻

Building your own app?

For more information on how to build scalable Forge apps, please reach out to us! We are happy to help you with your Forge development and share our experience with you. Reach out to us via e-mail or schedule a meeting with us via our Calendly link.