requestGraph

You can use requestGraph to make a request to the Atlassian platform GraphQL API, from within your Forge app. This is suitable for Atlassian products that expose GraphQL API endpoints, such as Compass.

Alternatively, Compass Forge apps can use GraphQL API Toolkit to execute pre-written queries (instead of using requestGraph).

The client includes an Authorization header based on the context-bound fetch call.

To use requestGraph, 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()
    .requestGraph(
      query, variables, headers
    );
const status = result.status;

Method signature

1
2
// Only authenticated calls are permitted
api.[asApp | asUser]().requestGraph(query, variables, headers) => 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.

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.

Experimental endpoints

In the GraphQL API reference, some endpoints may still be experimental. The queries and mutations for these fields are documented with a Field Lifecycle section that includes the following notice:

1
2
This field is in the 'EXPERIMENTAL' lifecycle stage

The Field Lifecycle section will include specific instructions on how to query the field. In particular, any requests to experimental Compass endpoints need to include the X-ExperimentalApi: compass-beta header.

Parameters

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.

Authenticated example

Fetch the name of the current user:

1
2
import 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.