requestJira

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
2
import api, { route } from '@forge/api';

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

1
2
const result = await api
    .asApp()
    .requestJira(
      path[, options]
    );
const status = result.status;

Method signature

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

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 `asApp`, you can use the Authorize API to verify user permissions before making the request.
`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.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 asApp, you can use the Authorize API to verify user permissions before making the request.

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.

Path construction (route)

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.

Usage

1
2
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}`;

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.

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.

Parameters

Name Type Description

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

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

Authenticated example

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

1
2
api.[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
2
api.[asApp | asUser]()
    .requestJira(route`/rest/api/3/issue/${issueKey}/watchers`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "Accept": "application/json"
        },
        body: JSON.stringify(`${accountId}`)
    });

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
api.requestJira(route`/rest/api/2/auditing/record`, {
  headers: {
    'Authorization': 'Basic <base64 token>'
  }
});