GraphQL

Airplane makes it easy to connect to GraphQL APIs. With GraphQL tasks, you can connect to existing GraphQL APIs from Airplane.

Getting started

This guide will get you up and running with an example GraphQL task.
We'll use the Airplane CLI airplane to demonstrate how to get started with a GraphQL task.
If you haven't yet, first install the Airplane CLI by following the instructions at Installing the CLI.

Create your task

Once you've installed and logged in to the CLI, navigate to the folder where you want to create your task and run:
bash
Copied
1
airplane tasks init
You'll be prompted for some information:
  • Enter a name for the task.
  • Select GraphQL as the kind.
  • Enter a name for the the definition file. The definition file contains task metadata as well as the content of the GraphQL request (e.g. find_user_by_email.task.yaml).

Resource

The GraphQL API resource configures the connection to your API. If you don't have an existing resource, visit the Resources settings page to add a new resource.
Open up the definition file (the file with extension .task.yaml) to configure the resource for your task.
Example:
yaml
Copied
1
graphql:
2
# Where internal_api is the slug of a created resource.
3
resource: internal_api

Parameters

Parameters allow you to prompt users for input before triggering your task. See Parameters for more information.
Open up the definition file (the file with extension .task.yaml) to add parameters to the task.
Example:
yaml
Copied
1
parameters:
2
- name: User ID
3
slug: user_id
4
type: shorttext
5
description: The ID of the user
Parameters can be passed into most fields of the GraphQL request as {{params.slug}}.
yaml
Copied
1
graphql:
2
variables:
3
userID: "{{params.user_id}}"
Parameters can be used in most fields, but they cannot be used in variable keys, URL parameter keys, or header keys.

Build your request

Specify the operation, variables, and other details of your GraphQL request in your task definition file.
Here, you'll be able to interpolate the parameters you specified earlier. By specifying {{params.slug}}, the parameter value will get inserted into the request.
Example:
yaml
Copied
1
graphql:
2
operation: |
3
query get_user($id: ID!) {
4
user(id: $id) {
5
id
6
name
7
email
8
}
9
}
10
variables:
11
id: "{{params.user_id}}"

Test your task locally

You can test the task locally before deploying by running airplane dev to start the Studio. The task will execute against local resources created in the Studio. Alternatively, enable fallback to test against remote resources.
bash
Copied
1
# Start the Studio and load in your_task
2
$ airplane dev your_task.task.yaml

Deploy to Airplane

Finally, run deploy to push your task to Airplane:
bash
Copied
1
airplane deploy your_task.task.yaml
Once deployed, go to the Tasks page to run and share your task!