Rate this page:

Fetch API

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

Import the runtime in function modules 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
api.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
api.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
api.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
api.asApp() => { requestJira: Fetch, requestConfluence: Fetch  }

Examples

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

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

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;
}

Get a list of issues from a public Jira project.

1
2
3
4
5
6
7
8
9
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
api.asUser() => { requestJira: Fetch, requestConfluence: Fetch  }

Examples

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

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

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;
}

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
27
28
29
30
import ForgeUI, {
  render,
  Text,
  Macro,
  useAction,
  useProductContext
} from '@forge/ui';
import api from '@forge/api';

const App = () => {
  const { contentId } = useProductContext();

  const getContent = async () => {
    const response = await api
      .asUser()
      .requestConfluence(`/rest/api/content/${contentId}`);

    return await response.json();
  }

  const data = useAction(() => {}, getContent());

  return (
    <Fragment>
      <Text>{JSON.stringify(data)}</Text>
    </Fragement>
  );
};
  
export const run = render(<Macro app={<App />} />);

Rate this page: