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 2import api, { route } from '@forge/api';
To check the status of a request, use status
as shown below:
1 2const result = await api .asApp() .requestBitbucket( path[, options] ); const status = result.status;
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 |
---|---|
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 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
.
1 2import { 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 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}`));
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: |
Make a request to GET
a repository on the Bitbucket workspace where the app is installed:
1 2api.[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 2api.[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}" } }` });
Rate this page: