Product fetch API

Forge API product fetch is a partial implementation of node-fetch and includes an Authorization header based on the context-bound fetch call.

Import the Forge API package in your app, as follows:

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

To check the status of a request, use status as shown below:

const result = await api
    .asApp()
    .[requestConfluence | requestJira](
      route`/rest/api/`
    );
const status = result.status;

See the Options section of the node-fetch documentation on GitHub for full implementation details.

route

You must use the route tagged template function to construct the path that's passed to the product fetch APIs. route is a tagged template function that runs encodeURIComponent on each interpolated parameter in the template string. This provides protection against security vulnerabilities, such as path traversal and query string injection.

Usage

import { route } from '@forge/api';

// With no parameters
route`/rest/api/3/myself`;

// With parameter: e.g. '/rest/api/3/issue/ISSUE-1'
route`/rest/api/3/issue/${issueKey}`;

// With query parameters: e.g. '/rest/api/3/issue/ISSUE-1?fields=summary'
route`/rest/api/3/issue/${issueKey}?fields=${fieldsToDisplay}`;

// With more complex query parameters: e.g. '/rest/api/3/issue/ISSUE-1?fields=summary' or '/rest/api/3/issue/ISSUE-1'
const queryParams = new URLSearchParams({
  ...(filterFields ? { fields: fieldsToDisplay } : {}),
});
route`/rest/api/3/issue/${issueKey}?${queryParams}`;

You have the option to bypass this requirement by using assumeTrustedRoute from @forge/api. However, you should only do this if absolutely needed because this puts you at risk of security vulnerabilities if used without a validated or trusted route.

Contextual methods

Interface

api.[contextMethod](): <{
  requestConfluence,
  requestJira,
}>

Methods

Method Description

api.asApp() Use this method to call an Atlassian API as the app developer.

Method	Description
`api.asApp()`	Use this method to call an Atlassian API as the app developer.
`api.asUser()`	Use this method to call an Atlassian API as the user of the app. If the user initiating the request has not granted permission to the app, the request is made without a valid `Authorization` header. If the API returns a `401` and there isn't a valid `Authorization` header, then an `Error` is thrown. If this error isn't caught, the user is prompted to grant access to the app. If the user grants access, the app is re-initialized. Note: This context method is only available in modules that support the UI kit.

api.asUser()

Use this method to call an Atlassian API as the user of the app.

If the user initiating the request has not granted permission to the app, the request is made without a valid Authorization header.

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

If this error isn't caught, the user is prompted to grant access to the app.
If the user grants access, the app is re-initialized.

Note: This context method is only available in modules that support the UI kit.

requestConfluence

Makes a request to the Confluence REST API.

Method signature

// Authenticated
api.[asApp | asUser]().requestConfluence(path[, options]) => Promise<Response>

// Unauthenticated (used for operations that do not support OAuth 2.0)
api.requestConfluence(path[, options]) => Promise<Response>

Parameters

Name Type Description

Name	Type	Description
`path`	`string`	A Confluence REST API operation path. See the Confluence Cloud platform REST API for more information. The path must be constructed using the route tagged template function.
`options`	`object`	See the node-fetch library’s Options documentation for the accepted values. Defaults: `{ 'content-type': 'application/json' }`

path

string

A Confluence REST API operation path. See the Confluence Cloud platform REST API for more information. The path must be constructed using the route tagged template function.

options

object

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

Defaults: { 'content-type': 'application/json' }

Authenticated example

Make a request to the /rest/api/content resource on the Confluence site where the app is installed.

api.[asApp | asUser]().requestConfluence(route`/rest/api/content`);

The asApp() function authenticates with the Atlassian products using a system user dedicated to your app. The system user is only a member of the default user group. This means the system user is not able to access private data such as Jira projects or Confluence spaces that are not visible to the default user group.

To access private data, use the asUser() function to access the content on behalf of your user. A user may not always provide consent for such access or have the required permissions, so ensure your app handles missing permissions.

To learn more about this issue and for updates on when this behavior is improved, see the FRGE-212 Jira issue.

Unauthenticated example

Make a request to the /rest/api/audit resource on the Confluence site where the app is installed, using basic authentication.

api.requestConfluence(route`/rest/api/audit`, {
  headers: {
    'Authorization': 'Basic <base64 token>'
  }
});

requestJira

Makes a request to the Jira REST API.