HTTP module¶

This module allows the user to make HTTP or HTTPS requests directly from Hexaly Modeler. This module supports the main features of the HTTP standard: custom headers, cookies, authentication and proxy.

The list of supported features largely depends on the Hexaly product used (Studio or Modeler). Features supported in the studio are constrained by browser security mechanisms.

Note

To use the features of this module, you have to put a special import statement at the begining of your HXM file: use http;

Module functions¶

http.send(options)¶

Send an HTTP request. The request configuration is done through the options parameter. All request parameters (including cookies and headers) must be supplied in the form of maps, whose expected keys and values are detailed below.

Parameters:: options (Map) – Options and content of the http request.
Return type:: HttpResponse

Classes¶

class HttpResponse¶

statusCode¶

Returns the status code of the HTTP response.

Return type:: int

headers¶

Returns a map containing the response headers. Headers are indexed from 0 to n-1. Each header is a map itself containing two fields: name and value. You’ll find more information on header formats in the table below. The returned map is read-only.

Return type:: map (array of headers)

cookies¶

Returns a map formatting the response cookies. Cookies are indexed from 0 to n-1. Each cookie is a map itself which follows the format detailed in a the cookies table below. The returned map is read-only.

Return type:: map (array of cookies)

findHeader(headerName)¶

Returns the value of the first header whose name is given as an argument to this function, or nil if no header with such name exists. The name is not case-sensitive. Calling findHeader("Content-type) or findHeader("content-type") returns the same result.

Return type:: string or nil

findHeader(headerName)

Returns the cookie with the given name or nil if no cookie with such name exists. The name is case-sensitive. Foo or foo are considered as two different cookies.

Return type:: map (cookie) or nil

asJson()¶

asJson(options)

Converts the response body into JSON. Several options can be used to customize the behavior of the JSON parser. The options must be specified in a map. The supported options are detailed at the end of this page.

You can call this method regardless of the type of content returned by the server. However, the Content-type is still used to determine the encoding of the document. If no encoding is specified, utf-8 is assumed by default. Note that an error is thrown is the specified encoding is not supported. The list of supported enocdings is available in this page.

Return type:: map

asText()¶

Converts the response body into text. This method will use the encoding specified by the server in the response (by reading the Content-type). If no encoding is specified, utf-8 is assumed by default.

This method can fail if the response is encoded using a non-supported charset. The list of supported encodings is available in this page.

Return type:: string

Options summary¶

Option name	Type	Mandatory	Mode	Description
method	enum	✓	studio, standalone	The request’s method: GET, POST, PUT, DELETE, HEAD, PATCH, TRACE, OPTIONS.
url	string	✓	studio, standalone	The request’s URL.
body	string or map		studio, standalone	The request’s body. It can be specified in the form of a string or a map. If a map is supplied, this module will attempt to convert it into a JSON document using the json module of the modeler. The encoding used for the string or the JSON document is utf-8.
headers	map of headers		studio, standalone	List of headers to send with the request, indexed from 0 to n-1. Each header must be supplied in the form of a map with two keys: name and value. See the headers table for more details.
cookies	map of cookies		standalone	List of cookies to send with the request, indexed from 0 to n-1. Each cookie must be supplied in the form of a map whose keys must correspond to the options detailed in the table below. It is recommended to use this option rather than supplying the cookies directly in the headers.
proxy	map with proxy options		standalone	Information about the proxy to be used to perform the request. If this option is left nil and the `http_proxy` and `https_proxy` environment variables are empty, no proxy will be used. Options must be entered in the form of a map in which each key must correspond to one of the options detailed in the table below.
username	string		studio, standalone	The username to use if the remote website requires “Basic” authentication.
password	string		studio, standalone	The password to use if the remote website requires “Basic” authentication.
timeout	int		studio, standalone	Time limit (in ms) for the request to complete. If the limit is exceeded, the request failed and the `send` method throws an exception.

Cookies specification¶

A cookie consists of at least a name and a value. Other parameters can also be optionally specified to control the validity period or the perimeter of the cookie. The table below gives details of the options you can set. The format expected by the send() function is also the same format in which the cookies returned by the remote server are presented.

In the send() function, cookies must be passed in the form of a map indexed from 0 to n-1. Each element of this map must itself be a map representing a cookie whose keys must correspond to the options given below.

Note

RFC 6265 limits the characters allowed for the name and value of cookies. Control characters, but also whitespaces, double quotes, commas, semicolons and backslashes are forbidden in cookie values. Many APIs and software applications use percent-encoding to escape these characters. This mechanism is not standardized and is not applied here.

If your cookies are likely to contain any of these characters, remember to escape them yourself using the mechanism of your choice (e.g. url-encoding or base64).

Note

The table below only applies if you are using Hexaly Modeler. It is not possible to set cookies with Hexaly Studio. This is because requests are made by the browser, which automatically transmits the cookies stored for that domain.

Option name	Type	Description
name	string	Cookie’s name.
value	string	Cookie’s value.
domain	string	Defines the domain on which the cookie will be valid. Setting the domain will make the cookie available to it, as well as to all its subdomains. If this parameter is not set, the cookie will only be valid for the current domain, without any sub-domains.
path	string	Cookie’s path.
secure	bool	Set to true if this cookie shall be send only over https.
sameSite	enum	Manages cookie sending behavior in the context of cross-site requests. The possible values are: `Strict`, `Lax` and `None`.

Headers¶

Headers are used to pass additional information to the HTTP server in relation with your request. A header consists of a name (case insensitive) and a value. Many headers are standardized, but it’s also possible to forge your own headers, provided the HTTP server understands them. Note also that the same header can be specified several times. The behavior adopted by the server depends on the header (aggregate the different values, or take only the first or last value).

In the send() function, headers must be passed in the form of a map indexed from 0 to n-1. Each element of this map must itself be a map representing a header with two keys: the name and the value of the header.

Below is a complete example of 2 correctly defined headers:

local headers = {
    { name: "Content-type", value: "application/json" },
    { name: "Etag", value: "0123456789ABCDEF" }
};

If you use Hexaly Studio, restrictions on the headers you can send apply for security reasons. Below is a complete list of restricted headers:

Accept-Charset                      Accept-Encoding
Access-Control-Request-Headers      Access-Control-Request-Method
Connection                          Content-Length
Cookie                              Date
DNT                                 Expect
Host                                Keep-Alive
Origin                              Permissions-Policy
Referer                             TE
Trailer                             Transfer-Encoding
Upgrade                             Via
Any header starting with Proxy-
Any header starting with Sec-

Proxy options¶

By default, Hexaly Modeler tries to honor the http_proxy or https_proxy environment variables if they are correctly set. If authentication is required, or if you want to change the URL set in the environment variable, you can also set your own proxy parameters by defining the proxy map in the global options. This map must contain one or more of the parameters listed below. All these parameters are optional.

Note

The table below only applies if you are using Hexaly Modeler in standalone mode. Hexaly Studio always uses the proxy settings configured for the browser. No further action is required, and all the proxy options will be simply ignored.

Proxy option	Type	Description
url	string	Proxy URL. Communication with the proxy can be made in http or https, regardless of the remote site to be contacted. You can specify a port using the classic URL notation, for example: `https://www.monproxy.com:8080`.
username	string	The username to use if the proxy requires authentication. Note that only Basic authentication is actually supported.
password	string	The password to use if the proxy requires authentication. Note that only Basic authentication is actually supported.
trustCertificate	string	If the proxy communicates via TLS, trust the certificate provided by the proxy, even if it is expired, self-signed or if the certification chain cannot be properly validated. Note that this option does not disable certificate verification on the destination hosts if they are themselves communicating over TLS. This option has no effect if the proxy does not communicate over TLS.
trustHost	string	If the proxy communicates via TLS, disable verification of the domain name indicated in the certificate supplied by the proxy, even if this does not correspond to the host initially contacted. The use of this option is not recommended, as it is very often the sign of a man-in-the-middle attack. Note that this option does not disable host name verification on the destination hosts if they are themselves communicating over TLS. This option has no effect if the proxy does not communicate over TLS.

Examples¶

HTTP POST¶

The following example makes an HTTP Post request sending a JSON body to an open API. The API returns a JSON response printed by the example:

// Don't forget to import the http module at the beginning of your file
use http;

...

body = {
    "title": "foo",
    "body": "bar",
    "userId": 1
};

response = http.send({
    url: "https://jsonplaceholder.typicode.com/posts/",
    method: "POST",
    body: body,
    headers: {
        { name: "Content-Type", value: "application/json" }
    },
    timeout: 100
});

if (response.statusCode != 201) {
    throw "The request has failed, received status code : " + response.statusCode;
}

println(response.asJson());

The display of the response shows the following map:

{body : bar, id : 101, title : foo, userId : 1}