Skip to main content
Version: 1.0

HTTP

The HTTP service provides functionality for sending HTTP/HTTPS requests through the RPC methods HTTP.GET and HTTP.POST. Also a generic HTTP.Request RPC call is provided which allows sending several HTTP methods.

Authentication support​

Since version 1.0

URL strings with username and passwrod elements are supported as defined in WHATWG. The HTTP client will use the authentication credentials for resources protected by the basic and digest authentication schemes.

Errors​

Methods in the HTTP service will return an error response with code -103 for invalid or missing arguments or -108 if an unacceptable number of request headers was given. If the call is accepted, but the HTTP request fails, the error response will contain one of the following codes:

  • -104 "Deadline exceeded" when the request times out
  • -108 "Resource exhausted" if the response body payload was too large to handle
  • -114 "Unavailable" for other error conditions.

The error message will be prefixed with an additional, internal error code indicating the specific error condition:

  • -10: Name not resolved
  • -11: Sending data to remote peer failed
  • -12: Header parse error
  • -13: Unsupported encoding
  • -14: Response too big
  • -15: Body parse error
  • -16: Connection closed prematurely
  • -17: Too many redirects
  • -18: HTTP Error Response

HTTP.GET​

This method allows fetching resources using HTTP/HTTPS GET requests.

Request​

Parameters:

PropertyTypeDescription

url

string

Url address of the request. Required

timeout

number

Timeout in seconds. Optional

ssl_ca

string or null

Type of the TCP socket. Optional

ValueDescription

null

Default value, the built-in ca.pem TLS CA is used for HTTPS requests

user_ca.pem

The user-provided TLS CA is used for HTTPS requests, see Shelly.PutUserCA

*

Disabled certificate validation

Response​

Attributes in the result:

PropertyTypeDescription

code

number

Code of the HTTP response

message

string

Msssage of the HTTP response

headers

object

List of HTTP headers sent by the server

body

string

HTTP response body, if Content-Type is text or application/json

body_b64

string

base64 encoded HTTP response body, if body is binary data. Maximum accepted length is 16KB (16384 bytes)

HTTP.POST​

This method allows posting data and receiving response using HTTP/HTTPS POST requests.

Request​

Parameters:

PropertyTypeDescription

url

string

URL address of the request. Required

body

string

The request body. Required

body_b64

string

base64 encoded binary request body. Either body or body_b64 is allowed

content_type

string

Value of the Content-Type header sent with the request Optional, default is application/json

timeout

number

Timeout in seconds. Optional

ssl_ca

string or null

Type of the TCP socket. Optional

ValueDescription

null

Default value, the built-in ca.pem TLS CA is used for HTTPS requests

user_ca.pem

The user-provided TLS CA is used for HTTPS requests, see Shelly.PutUserCA

*

Disabled certificate validation

Response​

Attributes in the result:

PropertyTypeDescription

code

number

Code of the HTTP response

message

string

Message of the HTTP response

headers

object

List of HTTP headers sent by the server

body

string

HTTP response body, if Content-Type is text or application/json

body_b64

string

base64 encoded HTTP response body, if body is binary data. Maximum accepted length is 16KB (16384 bytes)

HTTP.Request​

This method allows sending several HTTP methods through HTTP/HTTPS and receiving response. Currently supported are GET, POST, PUT, HEAD and DELETE.

HTTP.Request also exposes a few additional aspects of the HTTP request being made:

  • Can specify timeout for the operation -- seconds of inactivity which will abort the operation;
  • Can specify request headers. A maximum of 15 headers, with value sizes limited to 1024 bytes each will be accepted.
  • The total request length, including the URL with any GET arguments, headers and body, is limited to 8192 bytes.
  • Use PUT, HEAD and DELETE HTTP methods.

Request​

Parameters:

PropertyTypeDescription

method

string

Method to send. Valid values are GET, POST, PUT, HEAD, DELETE. Required

url

string

URL address of the request. Required

body

string

The request body. Disallowed for GET and HEAD and Required for POST and PUT.

body_b64

string

base64 encoded binary request body. Either body or body_b64 is allowed.

headers

object

User supplied headers for the request, keys are header names and values are header values. Optional. User-Agent and Content-Length headers are disallowed and will be replaced with default values if specified. Contnet-Type header defaults to application/json for body and application/octet-stream for body_b64 if not specified.

timeout

number

Timeout in seconds. Optional. Defaults to 15 seconds of inactivity.

ssl_ca

string or null

Type of the TCP socket. Optional

ValueDescription

null

Default value, the built-in ca.pem TLS CA is used for HTTPS requests

user_ca.pem

The user-provided TLS CA is used for HTTPS requests, see Shelly.PutUserCA

*

Disabled certificate validation

Response​

Attributes in the result:

PropertyTypeDescription

code

number

Code of the HTTP response

message

string

Message of the HTTP response

headers

object

List of HTTP headers sent by the server

body

string

HTTP response body, if Content-Type is text or application/json

body_b64

string

base64 encoded HTTP response body, if body is binary data. Maximum accepted length is 16KB (16384 bytes)

Examples​

HTTP.GET example​

http://192.168.33.1/rpc/HTTP.GET?url="http://10.33.53.21/rpc/Shelly.GetDeviceInfo"

Response

{
  "code": 200,
  "message": "OK",
  "headers": {
    "Server": "ShellyHTTP/1.0.0",
    "Content-Type": "application/json",
    "Content-Length": "232",
    "Connection": "close"
  },
  "body": "{\"id\":\"shellydev1-f008d1e2cb4c\", \"mac\":\"F008D1E2CB4C\", \"model\":\"SNSW-devX16EU\", \"gen\":2, \"fw_id\":\"20210908-124312/0.7.0-29-g0df1661-145-rpc-http-get-improvements-2\", \"ver\":\"0.7.0\", \"app\":\"Dev1\", \"auth_en\":false,\"auth_domain\":null}\r\n"
}

HTTP.POST example​

http://192.168.33.1/rpc/HTTP.POST?url="http://10.33.53.21/rpc/Sys.SetConfig"&body="{\"config\":{\"location\":{\"tz\":\"UTC\"}}}"

Response

{
  "code": 200,
  "message": "OK",
  "headers": {
    "Server": "ShellyHTTP/1.0.0",
    "Content-Type": "application/json",
    "Content-Length": "28",
    "Connection": "close"
  },
  "body": "{\"restart_required\":false}\r\n"
}

HTTP.Request example​

http://192.168.33.1/rpc/HTTP.Request?method="POST"&url="http://10.33.53.21/rpc/Sys.SetConfig"&body="{\"config\":{\"location\":{\"tz\":\"UTC\"}}}"

Response

{
  "code": 200,
  "message": "OK",
  "headers": {
    "Server": "ShellyHTTP/1.0.0",
    "Content-Type": "application/json",
    "Content-Length": "28",
    "Connection": "close"
  },
  "body": "{\"restart_required\":false}\r\n"
}

HTTP.GET With authentication credentials example​

http://192.168.33.1/rpc/HTTP.GET?url="http://admin:supersecretpassword@10.33.53.21/rpc/Shelly.Reboot"

Response

{
  "code": 200,
  "message": "OK",
  "headers": {
    "Connection": "close",
    "Content-Length": "4",
    "Content-Type": "application/json",
    "Server": "ShellyHTTP/1.0.0"
  },
  "body": "null"
}