Use the GraphQL API toolkit

The GraphQL API toolkit provides methods for making common requests to the Atlassian GraphQL Gateway from within a Forge app.

Before you begin

To access GraphQL APIs from your app, first install the latest GraphQL API toolkit package by running:

1
2
npm install @atlassian/forge-graphql

Use the GraphQL API toolkit

Import the @atlassian/forge-graphql package into your Forge app as follows:

1
2
import graphqlGateway from "@atlassian/forge-graphql";

The following example request uses the getComponent method to fetch details about a Compass component. When executing this code, be sure to define a componentId variable, which you can find on any component on your Compass site.

1
2
const {
  errors,
  data
} = await graphqlGateway.compass.asApp().getComponent({ componentId });

Let's understand this example getComponent request.

The graphqlGateway object is an instantiation of the Api class. There is a function in the graphqlGateway called compass which contains all the Compass related functionality. The return value of this compass function is an object defined by the CompassApi class. The resulting object has two methods defined in it, which are asUser() and asApp(). Both these methods return an object defined by the class CompassRequests. The CompassRequests class contains many methods that make requests to Atlassian GraphQL Gateway. The request defined in this example is a getComponent query. This query uses the parameters defined by the GetComponentInput type and returns an object of type ComponentPayload wrapped in an ApiPayload and returned as a Promise. The ApiPayload defines the errors and data properties while the ComponentPayload defines the type of the data returned.

Here's an example of a mutation:

1
2
import api, {
  CompassComponentType,
  CompassRelationshipType,
} from '@atlassian/forge-graphql';

const {
  errors,
  data: { component },
} = await graphqlGateway.compass.asUser().createComponent({
  cloudId: '4e381e6e-957b-3f8d-a8c2-2509478c45b1',
  name: 'Example Compass component',
  type: CompassComponentType.SERVICE,
  fields: {
    tier: 3,
  },
  relationships: [
    {
      type: CompassRelationshipType.DEPENDS_ON,
      nodeId:
        'ari:cloud:compass:4e381e6e-957b-3f8d-a8c2-2509478c45b1:component/c22ec0bd-121a-33de-b851-1d279e508dcb/d99ec9b2-1b37-57e1-ce04-8d454008cbf1f',
    },
  ],
});

This example uses the createComponent mutation. CreateComponentInput, which extends BaseComponentInput, defines the input to the mutation. The createComponent function returns an object of type ComponentPayload wrapped in ApiPayload and returned as a Promise.