Using HTTP APIs To Control Smart Home Devices

HTTP is probably the most common protocol used for controlling and configuring  smart home devices.

HTTP is also the protocol used for reading web pages, and so it is generally possible to use a web browser when dealing with HTTP APIs.

Before we look at an actual API we will first get familiar with HTTP.

HTTP Basics

Like most of the Internet protocols http it is a command and response text based protocol using a client server communications model.

The HTTP protocol is also a stateless protocol meaning that the server isn’t required to store session information, and each request is independent of the other.

This means:

• All requests originate at the client ( your browser)
• The server responds to a request.
• The requests(commands) and responses are in readable text.
• The requests are independent of each other and the server doesn’t need to track the requests.

A request consists of:

A command or request + optional headers + optional body content.

A response consists of:

A status code + optional headers + optional body content.

HTTP Requests Using a Browser

When making an HTTP request using a web browser a lot of the detail of the command is hidden and inserted automatically by the web browser.

However when using Smart Home APIs it may be necessary for you to include this.

Therefore it is important that you are aware of this.

HTTP Commands

The general structure is

Method + Resource Path + protocol version

there are 8 methods or verbs they are:

• GET – Requesting resource from server
• POST – submitting a resource to a server (e.g. file uploads)
• PUT -As POST but replaces a resource
• DELETE-Delete a resource from a server
• HEAD – As GET but only return headers and not content
• OPTIONS -Get the options for the resource
• PATCH -Apply modifications to a resource
• TRACE -Performs message loop-back

The ones we use when working with Smart home devices are the GET and POST methods.

When using a web browser the default method is GET and is hidden from the user.

It is not possible to manually use the POST method with a Web browser.

The resource path is a URL which you are already familiar with as it is what you are using to access this web page.

The general structure of a URL is shown below.

The URL can also include the port which is normally hidden by the browser, but you can manually include it as shown below:

The protocol version is optional and not normally used.

HTTP Headers and Body Content

These cannot be insert manually using the browser but are only really necessary when using the POST method.

Using the command line tool cURL is the most common way of using the POST command.

HTTP Responses and Response Codes

Each request has a response. The Response consists of a

• STATUS code And Description
• 1 or more optional headers
• Optional Body message can be many lines including binary data

Response Status codes are split into 5 groups each group has a meaning and a three digit code.

• 1xx – Informational
• 2xx – Successful
• 3xx -Multiple Choice
• 4xx– Client Error
• 5xx -Server Error

For example a successful page request will return a 200 response code and an unsuccessful a 400 response code.

You can find a complete list and their meaning here

For smart home APIs the body content is either plain text or more commonly JSON formatted data.

Note: JSON (JavaScript Object Notation} is a method of encoding JavaScript objects as strings so that they can be sent over a network or stored in a file.

Quick Questions

1. What HTTP methods do we usually use for smart home APIs.

2. Can we use a web browser to manually send a POST command?

3. Can our URL also include a port?

4. What method does a web browser use when we are reading a web page?

5. My API requires special headers to be sent can I use my web browser to do it?

Answers:

1. Get and POST methods
2. No
3. Yes
4. Get
5. No

Using The GET Method

The GET method is by far the easiest to use, but it is more limited than the POST method as you cannot send JSON data.

However you can pass in parameters to the API using the GET method.

These parameters are appended to the URL and consist of name and value pairs. The general structure is:

url?name1=value1&name2=value2

Notice the question mark.

e.g

http://192.168.1.41/myapi?username=steve&password=password

Examining  Simple HTTP APIs

Now we will look at the Tasmota and Shelly APis and how we use them to control the state of the device.

The API can be used not only for controlling the device state but also to change the device settings.

Tasmota API

The following screen shot is taken from the Tasmota web page and shows some API examples for turning a switch on and off using the GET Method.

The command can be sent using a standard web browser and note that %20 is a white space character.

We can enter the %20 or just use a space e.g

http://192.168.1.61/cm?cmnd=Power TOGGLE

This is what it looks like and notice the FireFox browser displays the response.

Shelly example

Below is a screen shot taken from the Shelly documentation for the switch control endpoint relay/id

For a Simple Shelly 1 switch we use the format:

http:/ipaddress/relay/0?turn=on

Valid values are:

turn=on,turn=off,turn=toggle

The screen shot below shows an example command and response using FireFox:

Questions

1. In the screen shot above for Tasmota what is the API endpoint to turn the switch on and off.
2. In the screen shot above for Shelly what is the API endpoint to turn the switch on and off.

Answers

1. cm
2. relay/0

Setting a timer for the Shelly Switch

The Shelly switch can be configure to change state and revert back to the original state after a period.

So if the current state in on we can turn it off, and have it turn back on. Here is a screen shot of the command and response.

After 60 seconds if we request the status we see this:

Related Tutorials and Resources:

• Understanding Smart Home APIs
• Controlling the Tasmota SonOff Switch with HTTP and Node-Red
• Controlling the Tasmota Switch with Node-Red and MQTT