$http.query

This is the principal method of the built-in JAICP 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.

Absolute URL

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");

Relative URL

A relative URL specifies a resource path relative to the base URL. This base URL should be set in the script beforehand via $http.config.

$http.config({
    url: {
        protocol: "https",
        host: "httpbin.org",
        port: 443
    }
});

// ...

$http.query("/get");

Request settings

Property	Type	Description
method	String	Request HTTP method. Possible values: GET (default), POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, TRACE.
query	Object	Parameters to be interpolated into the request URL.
body	Object or string	Request body.
form	Object	HTML form data.
fileUrl	String	Attached file URL.
fileName	String	Attached file name.
headers	Object	Request headers.
dataType	String	The type of the data contained in the request and expected in the response. Possible values: json, text, xml.
timeout	Number	Request timeout in milliseconds. Cannot exceed 25000.
cachingRequired	Boolean	Determines whether or not a successful response should be cached. false by default.
oauth2ResourceDetail	Object	OAuth 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.

URL without interpolated parameters

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

URL with interpolated parameters

$http.query("https://httpbin.org/${method}?param1=${param1}&param2=${param2}", {
    query: {
        method: "get",
        param1: "request",
        param2: "with params",
    }
});

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@just-ai.com",
        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

dataType	Content-Type
json	application/json
xml	application/xml
text	text/plain

Return value

The method returns an object with the following properties:

Property	Type	Description
isOk	Boolean	true if the request was successful and returned a 200–299 status code, false otherwise.
status	Number	HTTP response code (e.g. 200 or 401). Takes the value of -1 if an internal error occurred in the $http service.
data	Object or string	Data 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.
error	String	Error description. This property is empty if the request was successful.
response	Object	Full 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.