@forge/api

Forge API methods

API methods exposed during runtime in Forge apps. These include methods to simplify common actions such as making REST requests to Atlassian products.

See developer.atlassian.com/platform/forge/ for documentation and tutorials explaining Forge.

Usage

In your Forge app, include the following:

import API from '@forge/api';

Methods

The API exposes the following methods:

fetch

Fetches data from an HTTP server.

Signature:

fetch(url: string, options?: any) => Promise<object>

requestJira

Makes a request to the Jira REST API.

Signature:

requestJira(url: string, options?: any) => Promise<object>

requestConfluence

Makes a request to the Confluence REST API.

Signature:

requestConfluence(url: string, options?: any) => Promise<object>

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.

Signature

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

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.

Signature

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

Example

Make an authenticated call to the Jira myself API as the user of the app.

const getUserDisplayName = async (): Promise<string> => {
  // See https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-myself-get
  const response = API
    .asUser()
    .requestJira(`/rest/api/3/myself`);
  
  const json = await response.json();
  return json.displayName;
};

Support

See Get help for how to get help and provide feedback.