Part 2: Call a Jira API

This page introduces the Forge Javascript APIs. Using the @forge/api package, you'll learn how to make REST calls to an authenticated Jira endpoint.

Make an API call

In this section, you'll modify your app to call the Jira REST API. Using the Product Fetch API from the @forge/api package, you'll get the comments on a Jira issue in the form of an array and print the number of comments to the console.

The @forge/api package simplifies HTTP operations and contains other Forge APIs such as the Storage and Properties APIs. For this tutorial, you’ll also use a UI kit hook to get context information about the Jira issue the app is on.

1. In the app’s top-level directory, install the @forge/api package API by running:

   1

   npm install @forge/api

2. Restart your tunnel to use the new npm modules by running:

   1

   forge tunnel

3. Navigate to the src directory and open the index.jsx file. Import the @forge/api package by adding the following to the top of the file:

   1

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

4. Copy the following code to create a function that calls the Jira REST API by using the @forge/api package:

   1
   2
   3
   4
   5
   6
   7
   8

   const fetchCommentsForIssue = async (issueId) => {
     const res = await api
       .asApp()
       .requestJira(route`/rest/api/3/issue/${issueId}/comment`);
   
     const data = await res.json();
     return data.comments;
   };

   This function takes an issueId to call the REST API with path /rest/api/3/issue/${issueId}/comment.

5. Use the UI kit hook useProductContext to get the issueId to call fetchCommentsForIssue:

   1. Add useProductContext to the import statement as shown below:

      1

      import ForgeUI, { render, Fragment, Text, IssuePanel, useProductContext } from "@forge/ui";

   2. Add the following code to the App function directly before the return statement:

      1

      const context = useProductContext();

6. Fetch the comments for the page and log the output in the App function.

   1. Add the useState UI kit hook to the import statement as shown below:

      1

      import ForgeUI, { render, Fragment, Text, IssuePanel, useProductContext, useState } from "@forge/ui";

   2. Add the following code to the App function directly above the return statement:

      1
      2
      3

      const [comments] = useState(async () => await fetchCommentsForIssue(context.platformContext.issueKey));
      
      console.log(`Number of comments on this issue: ${comments.length}`);

7. Save the file. You'll see the tunnel output in the terminal showing the app code was reloaded:

   1
   2

   Reloading code...
   App code reloaded.

Your index.jsx file should look like the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

import api, { route } from "@forge/api";
import ForgeUI, { render, Fragment, Text, IssuePanel, useProductContext, useState } from "@forge/ui";

const fetchCommentsForIssue = async (issueId) => {
  const res = await api
    .asApp()
    .requestJira(route`/rest/api/3/issue/${issueId}/comment`);

  const data = await res.json();
  return data.comments;
};

const App = () => {
  const context = useProductContext();
  const [comments] = useState(async () => await fetchCommentsForIssue(context.platformContext.issueKey));

  console.log(`Number of comments on this issue: ${comments.length}`);

  return (
    <Fragment>
      <Text>Hello world!</Text>
    </Fragment>
  );
};

export const run = render(
  <IssuePanel>
    <App />
  </IssuePanel>
);

Test your app

To view your changes, reopen Jira then add a comment to an issue.

1. Create a new Jira issue, or open the one you created earlier.
2. Add a comment to the Jira issue. For example, a comment with Hello from the comments.
3. Refresh the Jira issue view.

4. Check the output of the tunnel in the terminal. The number of comments on the issue displays as follows:

   1
   2

   invocation: 158b5987a4724ee5 index.run
   INFO  05:01:33.408  158b5987a4724ee5  Number of comments on this issue: 1

Making an API call on behalf of a user

Up until this point, we've been using the .asApp() function to allow the app to make authorized API calls using its own user identity. In this example, you'll change the app to make API calls on behalf of the current user.

1. Find the fetchCommentsForIssue method in the index.jsx file.

2. Modify the API call by changing .asApp() to .asUser().

   Your index.jsx should look as follows:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31

   import api, { route } from "@forge/api";
   import ForgeUI, { render, Fragment, Text, IssuePanel, useProductContext, useState } from "@forge/ui";
   
   const fetchCommentsForIssue = async (issueId) => {
     const res = await api
       /* Modify this call by changing `.asApp()` to `.asUser()` */
       .asUser()
       .requestJira(route`/rest/api/3/issue/${issueId}/comment`);
   
     const data = await res.json();
     return data.comments;
   };
   
   const App = () => {
     const context = useProductContext();
     const [comments] = useState(async () => await fetchCommentsForIssue(context.platformContext.issueKey));
   
     console.log(`Number of comments on this issue: ${comments.length}`);
   
     return (
       <Fragment>
         <Text>Hello world!</Text>
       </Fragment>
     );
   };
   
   export const run = render(
     <IssuePanel>
       <App />
     </IssuePanel>
   );

3. Deploy your changes by running the forge tunnel or forge deploy command.

4. Open a new Jira issue, then click the Allow access button in the issue panel. This will authorize your app to access issues in the Jira project and make calls on your behalf.

Note, the .asUser() function inherits the product permissions of the user who has granted access to the app. This can cause different API responses between different users in the same app.

Next step

In the next tutorial, you'll learn how to make changes to your app's frontend using Forge UI kit components.