Forge Developer

Forge Developer

Storage API

Rate this page:

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:

1
import api from '@forge/api';

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

1
2
3
4
5
6
const result = await api
    .asApp()
    .[requestConfluence | requestJira](
      `/rest/api/`
    );
const status = result.status;

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

Contextual methods

Interface

1
2
3
4
api.[contextMethod](): <{
  requestConfluence,
  requestJira,
}>

Methods

MethodDescription
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.

requestConfluence

Makes a request to the Confluence REST API.

Method signature

1
2
3
4
5
// 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

NameTypeDescription
pathstring

A 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: { 'content-type': 'application/json' }

Authenticated example

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

1
api.[asApp | asUser]().requestConfluence('/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.

1
2
3
4
5
api.requestConfluence('/rest/api/audit', {
  headers: {
    'Authorization': 'Basic <base64 token>'
  }
});

requestJira

Makes a request to the Jira REST API.

Method signature

1
2
3
4
5
// Authenticated
api.[asApp | asUser]().requestJira(path[, options]) => Promise<Response>

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

Parameters

NameTypeDescription
pathstring

A 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: { 'content-type': 'application/json' }

Authenticated example

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

1
api.[asApp | asUser]().requestJira('/rest/api/2/myself');

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/2/auditing/record resource on the Jira site where the app is installed, using basic authentication.

1
2
3
4
5
api.requestJira('/rest/api/2/auditing/record', {
  headers: {
    'Authorization': 'Basic <base64 token>'
  }
});

Rate this page: