Runtime API

About

The runtime API provides methods to simplify common actions such as making REST requests to Atlassian products.

Usage

Import the runtime in Forge functions as follows:

1
import api from "@forge/api";

fetch

Fetches data from an HTTP server. See Options in the node-fetch documentation on GitHub for full implementation details.

Method signature

1
fetch(url[, options]) => Promise<Response>

Parameters

NameTypeDescription
urlstringThe full URL to the request to fetch data from.
optionsobjectSee the node-fetch library’s Options documentation for the accepted values. Defaults are the same as node-fetch.

requestJira

Makes a request to the Jira REST API.

Method signature

1
requestJira(apiPath[, options]) => Promise<Response>

Parameters

NameTypeDescription
apiPathstringA Jira REST API operation path. See the Jira Cloud platform REST API for more information.
optionsobject

See the node-fetch library’s Options documentation for the accepted values.

Defaults:

1
2
3
4
5
{
  'content-type': 'application/json'
  <Default for rest of the options is same as that of node-fetch>
}
        

Example

Make a request to the /rest/api/3/myself API on the Jira site where the app is installed.

1
api.requestJira('/rest/api/3/myself');

requestConfluence

Makes a request to the Confluence REST API.

Method signature

1
requestConfluence(url[, options]) => Promise<Response>

Parameters

NameTypeDescription
apiPathstringA Confluence REST API operation path. See the Confluence Cloud platform REST API for more information.
optionsobject

See the node-fetch library’s Options documentation for the accepted values.

Defaults:

1
2
3
4
5
{
  'content-type': 'application/json'
  <Default for rest of the options is same as that of node-fetch>
}
        

Example

Make a request to the /rest/api/3/myself API on the Confluence site where the app is installed.

1
api.requestConfluence('/rest/api/3/myself');

asApp

Use this method to call an Atlassian API as the app developer. The method adds an Authorization header for the app developer to a chained fetch call.

Method signature

1
asApp() => { requestJira: Fetch, requestConfluence: Fetch  }

Examples

  1. Make an authenticated call to the Jira myself API as the app developer.
    1
    api.asApp().requestJira('/rest/api/3/myself');
  2. Get the name of the app developer.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    async function getAppDeveloperDisplayName() {
      // See https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-myself-get
      const response = await api
        .asApp()
        .requestJira(`/rest/api/3/myself`);
      
      const json = await response.json();
      return json.displayName;
    }
  3. Get a list of issues from a public Jira project.
    1
    2
    3
    4
    5
    6
    7
    8
    async function getJiraIssues() {
      // https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-search-get
      const response = await api
        .asApp()
        .fetch(`/rest/api/3/search?jql=${encodeURIComponent('project = AC')}`);
      
      const json = await response.json();
      return json.issues;

asUser

Use this method to call an Atlassian API as the person using the app. The method adds an Authorization header for the request user to a chained requestJira or requestConfluence call.

If the user initiating the request has not granted permission to any sites, or the request is not made through a user interaction (such as, using a trigger) the request is made without a valid Authorization header.

If the API returns a 401 and there is not a valid Authorization header, then an Error is thrown.

  • If this error is left uncaught, the user is prompted to grant access to the app.
  • If the user grants access, the app is re-initialized.

Method signature

1
asUser() => { requestJira: Fetch, requestConfluence: Fetch  }

Examples

  1. Make an authenticated call to the Jira myself API as the user of the app.
    1
    api.asUser().requestJira('/rest/api/3/myself');
  2. Get the name of the current user.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    async function getUserDisplayName() {
      // See https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-myself-get
      const response = await api
        .asUser()
        .requestJira(`/rest/api/3/myself`);
      
      const json = await response.json();
      return json.displayName;
    }
  3. Complete function code to get the content of the Confluence page the app is invoked from.

    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
    import api from "@forge/api";
    import ForgeUI, {
      render,
      Text,
      Macro,
      useAction,
      useProductContext
    } from "@forge/ui";
    
    const App = () => {
      const query = `expand=body.view,body.editor,body.editor2,body.atlas_doc_format`;
      const { contentId } = useProductContext();
      const data = useAction(
        () => {},
        async () => {
          const response = await api
            .asUser()
            .requestConfluence(`/rest/api/content/${contentId}?${query}`);
          return await response.json();
        }
      );
    
      return <Text content={JSON.stringify(data)} />;
    };
    
    export const run = render(<Macro app={<App />} />);