api

Calls a REST API and returns the response. Use api for any HTTP endpoint an API profile names: your own services, public APIs, or a vendor's endpoints.

Fields

Every call goes through an API profile from the configuration. The profile carries the base URL, the headers sent on every call, and the connection pool to use; path is added to the end of the profile's URL. Headers and query parameters set on the command are added to the profile's, within what the profile allows: a profile value is replaced only when the profile marks it as one a command may override, and a new one is added only when the profile allows additions. The hosts an agent can reach are therefore the ones the profiles name.

Field	Type	Description
`onError`	command block	Commands to run if this command raises an uncaught error.
`profile`required	string	API profile from the configuration, which supplies the server's URL.
`path`	dynamic string	If set, this must be a relative path, which is added to the end of the profile's URL, and the profile's addPath decides whether a path may or must be added.
`method`	"GET" \| "POST" \| "PUT" \| "DELETE"	Defaults to POST when a body is given and GET otherwise.
`headers`	object of string → dynamic string	Headers for the call, typically used for authorization. Use sys.secret['NAME'] for credentials or API keys. With a profile, these are merged with the profile's headers: a header the profile already sets can only be changed when that header allows it, and a new header can only be added when the profile allows headers to be added.
`queryParams`	object of string → dynamic string	Query parameters added to the URL. With a profile, these are merged with the profile's query parameters: one the profile already sets can only be changed when that parameter allows it, and a new one can only be added when the profile allows query parameters to be added.
`body`	dynamic dict	The JSON body of the request.
`timeout`	dynamic string or integer	Timeout for this call, in seconds.

Result

The response body is the command's result, available as result in the next command. A JSON response is parsed into a Python object. A text response is returned as a string, and a binary response as bytes. A response labelled JSON, or without a content type, that is not valid UTF-8 is returned as a base64 string. An empty body returns the HTTP status code as a number instead. The command does not check the status code. A timeout or a connection failure raises an error, which onError can catch.

Example

Look up the caller's location, then the hourly forecast

"api": {
  "profile": "ip2location",
  "queryParams": {
    "ip": "{ result }",
    "key": "{ sys.secret['IP2LOCATION_KEY'] }"
  }
},
"var": {
  "location": "{ result }"
},
"api.forecast": {
  "profile": "weather",
  "path": "{ f'/points/{location['latitude']},{location['longitude']}' }"
}

Rules

Only GET, POST, PUT and DELETE are supported.
Keep credentials out of the definition. Read them with sys.secret[...] in a header, or put them in the API profile.
Timeouts default to the connection pool's settings. timeout overrides the default for this call.