Last updatedJul 26, 2021

Rate this page:

Part 2: Call a Confluence API

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

This is part 2 of 3 in this tutorial. Complete Part 1: Build a Confluence hello world app before working on this page.

Make an API call

In this section, you'll modify your app to call the Confluence REST API. Using the Product Fetch API from the @forge/api package, you'll get the comments on a Confluence page in 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 page the app is on.

Modify your app’s code to call the Confluence REST API that gets the comments on a page. You’ll use the returned array to count the number of comments and write it to the Forge logs. You’ll use the Product Fetch API in the runtime to make the REST call. The runtime API simplifies some operations, including HTTP calls. You’ll also use a UI kit hook to get context information about the page 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 Confluence REST API by using the @forge/api package:

    1
    2
    3
    4
    5
    6
    7
    8
    const fetchCommentsForContent = async (contentId) => {
      const res = await api
        .asUser()
        .requestConfluence(route`/rest/api/content/${contentId}/child/comment`);
    
      const data = await res.json();
      return data.results;
    };

    This function takes the contentId for a page to call the REST API with path /rest/api/content/{contentId}/child/comment.

  5. Use the UI kit hook useProductContext to get the contentId to call fetchCommentsForContent:

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

      1
      import ForgeUI, { render, Fragment, Text, 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 UI kit hook useState to the import statement.
    2. Add the following code to the App function directly above the return statement:

      1
      2
      3
      const [comments] = useState(async () => await fetchCommentsForContent(context.contentId));
      
      console.log(`Number of comments on this page: ${comments.length}`);

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, Macro, useProductContext, useState } from '@forge/ui';

const fetchCommentsForContent = async (contentId) => {
  const res = await api
    .asUser()
    .requestConfluence(route`/rest/api/content/${contentId}/child/comment`);

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

const App = () => {
  const context = useProductContext();
  const [comments] = useState(async () => await fetchCommentsForContent(context.contentId));

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

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

export const run = render(
  <Macro
    app={<App />}
  />
);

Test your app

  1. First, since we added an API request, we need to enable the permissions for calling the Confluence content API by adding the required OAuth2 scopes with the forge lint command.

    1
    forge lint --fix

    The forge lint command adds required scopes automatically to the manifest.yml file (in this case, read:confluence-content.summary).

    Learn more about adding scopes to call an Atlassian REST API.

  2. Because we modified the app's permissions, we also need to upgrade the app installation by running:

    1
    forge install --upgrade
  3. Restart the tunnel so we can see the console output of the app:

    1
    forge tunnel
  4. Add a comment to the Confluence page that contains your macro. For example, a comment with Hello from the comments.

  5. Refresh the Confluence page that contains your macro.
  6. Check the output of the tunnel in the terminal. The number of comments on the page displays as follows:

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

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.

A button to go back a page A button to go to the next tutorial

Rate this page: