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:
bashCopied1airplane 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:
yamlCopied1graphql:2# Where internal_api is the slug of a created resource.3resource: 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:
yamlCopied1parameters:2- name: User ID3slug: user_id4type: shorttext5description: The ID of the user
Parameters can be passed into most fields of the GraphQL request as
{{params.slug}}
.yamlCopied1graphql:2variables:3userID: "{{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:
yamlCopied1graphql:2operation: |3query get_user($id: ID!) {4user(id: $id) {5id6name78}9}10variables:11id: "{{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, run the command with the --env
flag to test your task with
remote resources.bashCopied1# Start the Studio and execute your_task against prod resources2# The --env flag will use the GraphQL resource and configs defined in the prod environment3$ airplane dev your_task.task.yaml --env prod
Deploy to Airplane
Finally, run deploy to push your task to Airplane:
bashCopied1airplane deploy your_task.task.yaml
Once deployed, go to the Tasks page to run and share your task!