|  Developer
Updated on January 3, 2022

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 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 , the HTTP connection will be closed if a HTTP response contains status codes in the range [, ]. 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 field . = . Default value: true.
verbose bool Will allow the module to be more verbose in logging mode . 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

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 boolean flag set to 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 is , multiple headers with the same name will be parsed, stored, passed to an HTTP-server. Also, an 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:
  • The file doesn’t exist:
  • Plugin doesn’t have permissions to the file:
  • Wrong format of parameter:
  • Limit of parameter is reached:
  • Limit of connections is reached