http.request()

Configures and starts a new asynchronous HTTP request. Returns connection identifier.

Edit

Arguments: options: table

Table Field	Type	Required	Description
url	string	+	Full url for making connection( can contain custom port )
certs	object	–
certs.ca	string	–	Path to file with certificates chain to verify server’s certificate in PEM format( in HUB:zwave/certs/server.ca format )
certs.key	string	–	Path to file with private key of client in PEM format (only if server requires client authentication via client certificates)( in HUB:zwave/certs/server.ca format )
certs.public	string	–	Path to file with certificate of client in PEM format (only f server requires client authentication via client certificates)( in HUB:zwave/certs/server.ca format )
skip_security	bool	–	Skip any security checks: check date, domain, and self-signed certificates criteria. Default value: false.
type	string	–	Type of request. Possible value: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE. Default value: GET.
content_type	string	–	Type of sending content
user	string	–	User name
password	string	–	User password
headers	object / array of objects	–	Custom request headers. See below.
keep_alive	bool	–	Keep HTTP request alive after establishing connection. Each plugin can have not more than 50 “alive” connections. Default value: false.
repeat_allowed	bool	–	Allows sequential repeat_request() call after the request is completed. Otherwise, allows to get multiple responses on a single request. Default value: true.
content_length	int	–	Length of content data in bytes
data	string / binary	–	Data for sending
last	bool	–	Does all data was sent or not? Default value: true. If this field is false then http_data_send event would be generated for sending next part of data for this request.
redirection	int	–	Max number of allowed redirection. Default value: 3. Max value can be: 15.
handler	string	+	Path to script file of plugin which should be executed when any event of connection would be generated( in HUB:my_plugin/http_receive.lua format)
user_data	any	–	User data that was passed to an http.request() call. Can be of any valid type: string, number, boolean, array, object. If user_data is null, the value will not be set.
new_data_buffer	int	–	Preferred size in bytes of buffer which should be used for receiving new data via http_data_received event. Minimal possible size: 32, max possible size: 500000 (Linux) or 1024 (RTOS).
new_data_cache	bool	–	Do not send http_data_received event unless buffer is full or end of response (or it’s significant part) was detected. Default value: true. When disabled, event will be triggered immediately after new portion of data received (useful for custom format response streams) thus increasing amount of events with smaller portions of data.
timeout	int	–	Timeout in milliseconds for waiting response. Default value: 30000 milliseconds. Max possible value: 86400000 milliseconds( 24 hours ).
connect_timeout	int	–	Timeout in milliseconds for establishing connection. Default value: 10000 milliseconds. Max possible value: 600000 milliseconds.
fail_on_error	bool	–	If true, the HTTP connection will be closed if a HTTP response contains status codes in the range [400, 599]. Otherwise, the HTTP-client will proceed to download document’s body till the end, and then, will generate the http_connection_closed event with the HTTP status code according to the HTTP-server response. The reason field http_connection_closed.reason = {“code”: 5, “text”: “Closed by server” }. Default value: true.
verbose	bool	–	Will allow the module to be more verbose in logging mode TRACE. Default value: false.
multiple_headers	bool	–	Will allow the request to use all headers with the same name passed as a response or as a request. Default value: false. If true, the http_data_received event will serialize its headers as an array, not as object.

The headers collection

There are two ways to set a list of headers for an HTTP request: using an object and using an array. First one was implemented and used by default by previous versions of the http module.

Actual description of that way is:

Table Field	Type	Required	Description
headers	object	–	Custom request headers
headers.{header_name}	string	+	Value of header names <header_name>

This way of specifying headers avoid user from using multiple headers of the same name with different values.

The updated way to specify headers collection is to use multiple_headers boolean flag set to true and passing an array of headers as an array of objects with (key, value) pairs, where key is a header name and value is a header value.

If multiple_headers is true, multiple headers with the same name will be parsed, stored, passed to an HTTP-server. Also, an http_data_received event will store the headers in the same manner.

Table Field	Type	Required	Description
headers	array of objects	–	Request headers. Supports multiple headers with the same name.
headers.[].key	string	+	Name of header record
headers.[].value	string	+	Value of header record

Edit

string, id of the request

Edit

Required parameter didn’t define: parameter_name
The file doesn’t exist: file_path
Plugin doesn’t have permissions to the file: file_path
Wrong format of parameter: parameter_name
Limit of parameter is reached: parameter_name
Limit of connections is reached