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:
bash
Copied
1
airplane 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:
yaml
Copied
1
rest:
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 REST request as {{params.slug}}.
yaml
Copied
1
rest:
2
  urlParams:
3
    userID: "{{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:
yaml
Copied
1
rest:
2
  configs:
3
    - API_KEY
Configs can then be passed into most fields of the REST request as {{configs.name}}, in a similar manner to parameters.
yaml
Copied
1
rest:
2
  headers:
3
    X-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:
yaml
Copied
1
rest:
2
  method: POST
3
  path: /users/{{params.user_id}}
4
  bodyType: json
5
  body:
6
    name: "{{params.user_name}}"
7
    type: 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.
bash
Copied
1
# Start the Studio and execute your_task against prod resources
2
# The --env flag will use the rest resource and configs defined in the prod environment
3
$ airplane dev your_task.task.yaml --env prod

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!

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:
javascript
Copied
1
// 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:
javascript
Copied
1
// Interpolated JSON body.
2
{
3
    "location": "NYC",
4
    "count": 50
5
}

Files in forms
You can attach files to your forms with file type parameters.
yaml
Copied
1
rest:
2
  bodyType: form-data
3
  formData:
4
    file: "{{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.
Next: Task configuration
PrivacyTermsSupport