RESTful Switch

The rest switch platform allows you to control a given endpoint that supports a RESTful API. The switch can get the state via GET and set the state via POST on a given REST resource.

Configuration

To enable this switch, add the following lines to your configuration.yaml file:

# Example configuration.yaml entry
switch:
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT

Configuration Variables

resource

(string)(Required)

The resource or endpoint that contains the value.

method

(string)(Optional)

The method of the request. Supported post or put.

Default value:

post

name

(string)(Optional)

Name of the REST Switch.

Default value:

REST Switch

timeout

(integer)(Optional)

Timeout for the request.

Default value:

body_on

(string)(Optional)

The body of the POST request that commands the switch to become enabled. This value can be a template.

Default value:

true

body_off

(string)(Optional)

The body of the POST request that commands the switch to become disabled. This value can also be a template.

Default value:

false

is_on_template

(string)(Optional)

A template that determines the state of the switch from the value returned by the GET request on the resource URL. This template should compute to a boolean (True or False). If the value is valid JSON, it will be available in the template as the variable value_json. Default is equivalent to '{{ value_json == body_on }}'. This means that by default, the state of the switch is on if and only if the response to the GET request matches.

username

(string)(Optional)

The username for accessing the REST endpoint.

password

(string)(Optional)

The password for accessing the REST endpoint.

headers

(string | list)(Optional)

The headers for the request.

verify_ssl

(boolean)(Optional)

Verify the SSL certificate of the endpoint.

Default value:

true

Make sure that the URL matches exactly your endpoint or resource.

Example

Switch with templated value

This example shows a switch that uses a template to allow Home Assistant to determine its state. In this example, the REST endpoint returns this JSON response with true indicating the switch is on.

{"is_active": "true"}

switch:
  - platform: rest
    resource: http://IP_ADDRESS/led_endpoint
    body_on: '{"active": "true"}'
    body_off: '{"active": "false"}'
    is_on_template: '{{ value_json.is_active }}'
    headers:
      Content-Type: application/json
    verify_ssl: true

body_on and body_off can also depend on the state of the system. For example, to enable a remote temperature sensor tracking on a radio thermostat, one has to send the current value of the remote temperature sensor. This can be achieved by using the template '{"rem_temp":{{states('sensor.bedroom_temp')}}}'.