Rate this page:
The product fetch API enables you to make requests to Atlassian product APIs from
within your Forge app. The client includes an Authorization
header based on the
context-bound fetch call.
Import the Forge API package in your app, as follows:
1 2import api, { route } from '@forge/api';
To check the status of a request, use status
as shown below:
1 2const result = await api .asApp() .[requestConfluence | requestJira]( route`/rest/api/` ); const status = result.status;
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.
1 2import { 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.
1 2api.[contextMethod](): <{ requestConfluence, requestJira, }>
Method | Description |
---|---|
api.asApp() | Use this method to call an Atlassian API as the app, using the app user. If your app has all the required permissions, the request will work regardless of who uses the app. |
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 If the API returns a
Note: This context method is only available in modules that support the UI kit. |
Makes a request to the Confluence REST API.
1 2// 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>
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: |
Make a request to the /wiki/rest/api/content
resource on the Confluence site
where the app is installed:
1 2api.[asApp | asUser]().requestConfluence(route`/wiki/rest/api/content`);
Make a request to the /wiki/rest/api/audit
resource on the Confluence site where
the app is installed, using basic authentication:
1 2api.requestConfluence(route`/wiki/rest/api/audit`, { headers: { 'Authorization': 'Basic <base64 token>' } });
Makes a request to the Jira REST API.
1 2// 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>
Name | Type | Description |
---|---|---|
path | string | A Jira REST API operation path. See the Jira 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: |
Make a request to the /rest/api/3/myself
resource on the Jira site where the app is installed:
1 2api.[asApp | asUser]().requestJira(route`/rest/api/3/myself`);
By default, the request method type is GET
. To send another request type, use the options
object. This example shows setting the method to POST
to add a watcher to an issue:
1 2api.[asApp | asUser]() .requestJira(route`/rest/api/3/issue/${issueKey}/watchers`, { method: "POST", headers: { "Content-Type": "application/json", "Accept": "application/json" }, body: JSON.stringify(`${accountId}`) });
Make a request to the /rest/api/2/auditing/record
resource on the Jira site where
the app is installed, using basic authentication:
1 2api.requestJira(route`/rest/api/2/auditing/record`, { headers: { 'Authorization': 'Basic <base64 token>' } });
Makes a request to the
Atlassian platform GraphQL API,
for Atlassian products that expose GraphQL API endpoints. For example, you can make Compass requests
using requestGraph
. Compass requests need to include the X-ExperimentalApi: compass-beta
header.
Compass Forge apps can use the GraphQL API Toolkit
to execute pre-written queries, as an alternative to the requestGraph
method.
1 2// Only authenticated calls are permitted api.[asApp | asUser]().requestGraph(query, variables, headers) => Promise<Response>
Name | Type | Description |
---|---|---|
query | string | The GraphQL query or mutation. |
variables | object | Variables to be used in the GraphQL query. |
headers | object | HTTP headers to be included in the request. |
Fetch the name of the current user:
1 2import api from '@forge/api'; import ForgeUI, { useEffect, useState } from '@forge/ui'; const [result, setResult] = useState(null); const query = "query { me { user { name } } }"; const variables = { "key1": "value1", "key2": "value2" }; const headers = { "key1": "value1", "key2": "value2" }; useEffect(async () => { const request = await api.asApp().requestGraph(query, variables, headers); setResult(request.json()); }, []); if(result) { console.log(result.data ? result.data.me.user.name : "No data"); console.log(result.errors ? result.errors : "No errors"); };
Successful queries return their result in the data
object. Any errors are returned
as an array in the errors
object.
Rate this page: