You can use requestJira
to make a request to the
Jira REST API
from within your Forge app.
The client includes an Authorization
header based on the
context-bound fetch call.
To use requestJira
,
import the Forge API package in your app:
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() .requestJira( path[, options] ); const status = result.status;
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>
When making an authenticated API call, you can specify whether to use the app (asApp
) or its user (asUser
) as the context:
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. When using |
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. |
You must use the route
tagged template function to construct the path that's passed to the product
fetch
APIs. route
blocks unsafe interpolated parameters in the path and encodes the query
parameters using encodeURIComponent
. 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}`;
When route
is called, the Forge runtime also checks for possible path manipulation attempts
(for example, issueKey
or repo_slug
coming from the user as ../../../evil_api_call
), escaping or blocking as needed.
If the URL is constructed separately, the runtime might throw an exception for this as a false positive. This is because the runtime has no way of knowing which parts might have been manipulated by the user.
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>' } });
Rate this page: