REST
It's easy to send REST requests from Airplane. With REST tasks, you can build/use existing APIs and have Airplane act as an interface to them.
Getting started
This guide will get you up and running with an example REST task.
We'll use the Airplane CLI
airplane
to demonstrate how to get started with a REST 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
REST
as the kind. - Enter a name for the the definition file. The definition file contains task metadata as well
as the content of the REST request (e.g.
delete_user_by_email.task.yaml
).
Resource
The REST 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:
yamlCopied1rest: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 REST request as
{{params.slug}}
.yamlCopied1rest:2urlParams:3userID: "{{params.user_id}}"
Parameters can be used in most fields, but they cannot be used in URL parameter keys or header keys.
Config variables
Config variables are team-wide values that can be shared across multiple tasks. See
Config variables for more information on config variables.
Open up the definition file (the file with extension
.task.yaml
) to attach configs to the
task.Example:
yamlCopied1rest:2configs:3- API_KEY
Configs can then be passed into most fields of the REST request as
{{configs.name}}
, in a similar
manner to parameters.yamlCopied1rest:2headers:3X-API-KEY: "{{configs.API_KEY}}"
Build your request
Specify the method, path, and other details of your REST 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:
yamlCopied1rest:2method: POST3path: /users/{{params.user_id}}4bodyType: json5body:6name: "{{params.user_name}}"7type: name
A user who runs this task with
user_id=123
& user_name=Bob
would make a POST to /users/123
with JSON body { "name": "Bob" }
.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 rest 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!
Interpolation
JSON body
When constructing a body using a JSON object, you can produce a value using
JS templates. Templates are represented as string values with
double-quotes:
javascriptCopied1// Example JSON body.2{3"location": "{{params.location}}",4"count": "{{params.count}}"5}
Here,
location
is a string and count
is an integer. After interpolation, the resulting body
looks something like this:javascriptCopied1// Interpolated JSON body.2{3"location": "NYC",4"count": 505}
Files in forms
You can attach files to your forms with file type parameters.
yamlCopied1rest:2bodyType: form-data3formData:4file: "{{params.my_file}}"
For
form-data
forms, the contents of your file are directly attached to the body without any
mutations. For x-www-form-urlencoded
forms, the contents of your file are base64-encoded before
being attached. Note that the value of the form field must be the single
JS template expression that is the value of the file parameter value.