Skip to main content

$http.query

This is the principal method of the built-in Tovie Platform HTTP client. It executes an HTTP request to an external URL.

It accepts two arguments: a string with the request URL and an object containing the request settings.

$http.query("https://httpbin.org/get?param=${param}", {
method: "POST",
query: { param: "query param value" },
body: { key: "body key value" },
headers: {
"Content-Type": "application/json",
"Authorization": "Basic " + $secrets.get("HTTPBIN_BASIC_AUTH")
},
dataType: "json",
timeout: 10000
});

Request URL

The request URL may be either absolute or relative.

An absolute URL begins with the http:// or https:// protocol and specifies the full path to the resource where the request will be sent.

$http.query("https://httpbin.org/get");

Request settings

PropertyTypeDescription
methodStringRequest HTTP method. Possible values: GET (default), POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, TRACE.
queryObjectParameters to be interpolated into the request URL.
bodyObject or stringRequest body.
formObjectHTML form data.
fileUrlStringAttached file URL.
fileNameStringAttached file name.
headersObjectRequest headers.
dataTypeStringThe type of the data contained in the request and expected in the response. Possible values: json, text, xml.
timeoutNumberRequest timeout in milliseconds. Cannot exceed 25000.
cachingRequiredBooleanDetermines whether or not a successful response should be cached. false by default.
oauth2ResourceDetailObjectOAuth 2.0 authorization settings.

Setting the HTTP method

Specify the method property in the request settings to configure the HTTP method. Additionally, you can use alternative $http shorthands for the most commonly performed actions:

  • $http.get
  • $http.post
  • $http.put
  • $http.delete

These methods have the same signature and behavior as $http.query. However, they automatically assign the appropriate value to the method property.

Interpolating URL parameters

The request URL can contain expressions within a ${} character sequence. When the request is executed, these expressions are replaced with the corresponding values from the query object.

$http.query("https://httpbin.org/get?param1=request&param2=with%20params");

Sending HTML forms

If you want to send contact a resource that accepts requests as HTML forms, use the form property instead of body to send the form data.

A request with this property will have its Content-Type header automatically set to application/x-www-form-urlencoded. The form fields will have the appropriate encoding.

$http.query("https://httpbin.org/post?key=${value}", {
method: "POST",
form: {
username: "John Doe",
email: "example@tovie.ai",
password: "qwerty"
}
});

Sending files

$http.query supports sending files as attachments. To do this, specify the fileUrl and (optionally) fileName properties in the request settings.

A request with these properties will have its Content-Type header automatically set to multipart/form-data. The request will be sent as an HTML form with a file field containing the binary-encoded file contents.

$http.query("https://httpbin.org/post", {
method: "POST",
fileUrl: "https://example.com/image.png",
fileName: "image.png"
});
note

If you don’t provide fileName but fileUrl contains a file name with an extension, this name will be used. Otherwise it will be a random UUID.

Request and response data types

Use the dataType property to specify the type of the data contained in the request and expected in the response. Take note of how it interacts with the Content-Type request header.

Content-Type Content-Type
dataType
  • The request is assigned the specified Content-Type.
  • The response is processed based on the value of dataType.
  • The request is assigned a Content-Type header corresponding to dataType.
  • The response is processed based on the value of dataType.
dataType
  • The request is assigned the specified Content-Type.
  • The response is processed in the format corresponding to the received Content-Type.
  • The request is assigned a Content-Type header with the value of application/json.
  • The response is processed in the format corresponding to the received Content-Type.
How dataType is mapped to Content-Type
dataTypeContent-Type
jsonapplication/json
xmlapplication/xml
texttext/plain

Return value

The method returns an object with the following properties:

PropertyTypeDescription
isOkBooleantrue if the request was successful and returned a 200–299 status code, false otherwise.
statusNumberHTTP response code (e.g. 200 or 401). Takes the value of -1 if an internal error occurred in the $http service.
dataObject or stringData received in the response. Its type depends on the configured data type:
  • If set to json or xml, data contains the response body transformed into a JavaScript object.
  • If it is text or the response has another Content-Type header, data contains the response body as plain text.
errorStringError description. This property is empty if the request was successful.
responseObjectFull response dump, which can be used to extract data such as HTTP headers.

How to use

The following example illustrates a request to the OpenWeather API to receive the current weather forecast in a specified city.

note

The example assumes that you have obtained your own OpenWeather API key and saved it as an OPENWEATHER_API_KEY secret in your project.

require: city/cityEn.sc
module = sys.zb-common

theme: /

state: CurrentWeather
q!: * air temperature [in] $City *
script:
$temp.response = $http.get("https://api.openweathermap.org/data/2.5/weather?lat=${lat}&lon=${lon}&appid=${appid}&units=${units}", {
query: {
lat: $parseTree._City.lat,
lon: $parseTree._City.lon,
appid: $secrets.get("OPENWEATHER_API_KEY"),
units: "imperial"
}
});
if: $temp.response.isOk
a: Right now it’s {{Math.floor($temp.response.data.main.temp)}} °F in {{$parseTree._City.name}}.
else:
a: I couldn’t fetch the weather forecast. Please try again.
HTTP client limitations
  • $http.query executes all HTTP requests synchronously. User query processing is suspended until the HTTP request has returned a response.

  • You can have at most 15 calls to $http.query during the processing of a single user query. Should this limit be exceeded, the method will return a response with the status -1 and error Callback limit reached.