API actions usually need some input to run.
For example, when you want to get the details of an album in the Spotify Web API, you need to provide an Album ID.
There are several types of input you can give an API action.
Path
Path inputs are bits of data that will appear in the URL itself.
You specify where these bits go in the “API Action” configuration in AutoWeb and then specify details about these inputs in the “Inputs” section separately.
For example, to get an album’s tracks in the Spotify Web API you need to call the following URL: https://api.spotify.com/v1/albums/{id}/tracks
- https://api.spotify.com/v1/ is the base url that is defined in the main API configuration. This is the URL part that is the same for all Spotify API calls
- albums/{id}/tracks is the “Path” in the API Action configuration. As you can see you have part of the url in curly braces, namely {id}. This tells AutoWeb that that part of the URL is an input that should be configured separately
- Because you have {id} input in the URL you need to specify an input:
- “Key” has to be whatever is inside the curly braces, which is this case is “id“
- “Name” can be whatever you want. In this case you can set it to “Id“
- “Parameter type” has to be “Path” so AutoWeb can replace this input on the URL itself
- “Input Type” has to be “text” because this is a free form text input
After creating this input, if you use the action in Tasker you’ll see a new field show up where you can insert the Album Id. Whatever you insert there will then be inserted in the URL instead of {id}
Query
Query parameters are bits of data that are appended to the URL of an API call.
These don’t have to bet defined in the “API Action” configuration in AutoWeb. They will simply get appended at the end of the URL
For example, to search for something in the Spotify Web API you use the following URL: https://developer.spotify.com/web-api/search-item/
But then other query parameters need to be added
- q – the query you want to perform
- type – the type of stuff you want to search for
These should be configured as inputs with the
- “Key” set to the query parameter name (“q” or “type” in this example)
- “Name” to whatever you want. Can be “Query” and “Type” in this example
- “Parameter Type” set to “Query“
After creating, if you use the action in Tasker you’ll see new input fields. After inserting values for them and calling the API, they will be appended to the request URL.
For example, the request URL could be set to https://developer.spotify.com/web-api/search-item/?q=sia&type=artist
Header
Header parameters are bits of data that are sent with the API call in the HTTP headers
They work in the same way as the Query parameters but are added as headers instead of URL parameters
File
APIs can receive files which is when you use an input of this type.
For example the Google Drive API Simple Upload action receives a file as input.
Simply add an input with “Parameter Type” of “File” and you’re good to go. You can set “Key” and “Name” to whatever you want but they can usually be “file” and “File” respectively.
After creating an input of this type, if you use the action in Tasker you’ll see a new input field. When you click on it you’ll be prompted to select a file from your file browser.
When you run the API action the file will be sent alongside the request to the configured URL. In the Google Drive example that url is: https://www.googleapis.com/upload/drive/v2/files?uploadType=media
There can only be ony input of the type File for each API action
Body
There can only be one input of the type Body for each API action. The body is defined in the “Default Value” field of the input parameter.
The body of the request is usually a piece of data you want to send to the API so that it knows what it should do with your request.
It’s different from the path, query or header fields because you can usually send more complex data in the body, whereas in other types you can only send simple data.
Most APIs will receive a Body input in json format, but you can use any format in this field in AutoWeb. It’s totally free-form.
In AutoWeb you have a special way to add variables to the body.
For example in the Google Drive Update File API Action you can update a file by sending some json in the request body:
{
"title": "test",
"description": "This is a test",
"labels": {
"starred": true
}
}
{
"title": "
=:==:=
text
name
File Name
The name you want to give the file
=:==:=
",
"description": "This is a test",
"labels": {
"starred": true
}
}
- add a new line where the variable should be
- add “=:==:=” followed by a new line
- add “text” followed by a new line
- add a variable id followed by a new line (in this case “name“)
- add a variable name followed by a new line (in this case “File Name“)
- add a variable description followed by a new line (in this case “The name you want to give the file“)
- add “=:==:=” followed by a new line
If you add an input of the type Body with this value and then use the API action in Tasker, you’ll see a new input field with the name “File Name” and description “The name you want to give the file“. The value you use there will then be replaced in the body and sent with the API call.
If you want to make the rest of the fields variables here’s what it would look like:
{
"title": "
=:==:=
text
name
File Name
The name you want to give the file
=:==:=
",
"description": "
=:==:=
text
description
File Description
A short description of the file
=:==:=
",
"labels": {
"starred":
=:==:=
trueorfalse
starred
Starred
Whether this file is starred
=:==:=
}
}
Notice how 3 variables are created: “name“, “description” and “starred“.
You can use this variable format in any type of body data.
For example, if an API receives a body like
parameter=value
you can make “value” a variable by using a body like
parameter= =:==:= text value Value Some value for this parameter =:==:=
Don’t forget the new line at the end 🙂