requestBitbucket

You can use requestBitbucket to make a request to the Bitbucket REST API from within your Forge app. The client includes an Authorization header based on the context-bound fetch call. Endpoints labeled with Forge app scopes are available for use from Forge apps.

To use requestBitbucket, 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()
    .requestBitbucket(
      path[, options]
    );
const status = result.status;

Method signature

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

// Unauthenticated (used for operations that do not support OAuth 2.0)
api.requestBitbucket(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.

Relative path construction (route)

You can use the route tagged template function to construct the path passed to requestBitbucket. 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.

requestBitbucket expects workspaceId (not workspace slug) in the route path. workspaceId is available in resolver context for custom UI/UI Kit. For UI Kit, you can use the useProductContext hook to retrieve the workspaceId.

Usage

1
2
import { route } from '@forge/api';

// With no parameters
route`/rest/api/3/myself`;

// With parameter:
route`/2.0/repositories/${workspaceId}/${repoId}`;

// With query parameters:
route`/2.0/repositories/${workspaceId}/${repoId}/pullrequests?q=state="OPEN";

// With more complex query parameters: 
route`/2.0/repositories/${workspaceId}/${repoId}/pullrequests?q=state="OPEN" AND comment_count > 10`

Use routeFromAbsolute to make Bitbucket API requests with absolute URLs rather than relative paths. This is useful for following href links in Bitbucket API responses which are usually absolute URLs.

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.

Absolute path construction (routeFromAbsolute)

You can use the routeFromAbsolute tagged template function to construct an absolute URL that's passed to the Bitbucket fetch APIs. routeFromAbsolute allows you to follow href links embedded in Bitbucket API responses which are usually absolute URLs rather than relative paths.

For example:

1
2
// If you retrieved the first page of repo source file listing via the below request  
api.[asApp | asUser]().requestBitbucket(route`/2.0/repositories/${workspaceId}/${repoId}/src`);

// Then you can use routeFromAbsolute to paginate through to the next page via the below
// (assuming $firstPage.next is not null it will be an absolute URL)
api.[asApp | asUser]().requestBitbucket(routeFromAbsolute(`${firstPage.next}`));

Parameters

Name Type Description

Name	Type	Description
`path`	`string`	A Bitbucket REST API operation path. See the Bitbucket Cloud platform REST API for more information. The path must be constructed using the route or routeFromAbsolute 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 Bitbucket REST API operation path. See the Bitbucket Cloud platform REST API for more information. The path must be constructed using the route or routeFromAbsolute 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 GET a repository on the Bitbucket workspace where the app is installed:

1
2
api.[asApp | asUser]().requestBitbucket(route`/2.0/repositories/${workspaceId}/${repoId}`);

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 create a pull request comment:

1
2
api.[asApp | asUser]()
  .requestBitbucket(route`/2.0/repositories/${workspaceId}/${repoId}/pullrequests/${pullRequestId}/comments`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    body: `{
      "content": { "raw": "${comment}" }
    }`
  });