Understanding REST APIs

This implementation uses what is called a REST API interface. REST stands for REpresentational State Transfer. It is not really a protocol but it is a design strategy for transferring data using HTML. Basically you use the data of the URL that you are getting or putting to communicate with a remote device. You can find more information on REST design at http://www.restapitutorial.com/lessons/whatisrest.html or other similar websites.

In our implementation we are using the URL to transmit the protocol number, data value, and number of bits. So for example if your device is at IP address 196.168.1.105 you could simply browse to this web URL.

http://192.1 68.1.105/irsend/2/12345/20

The first thing after the IP address is the word "irsend". This would probably be unecessary because all of our commands to this device are in the form of an infrared send command. However we have implemented it this way so that if you wanted to send other commands to this device you can modify the program to do something different depending upon this first item after the IP address. Then  separated by slashes we have the protocol number which in this case is 2, the data value in decimal, optionally followed by a slash and the number of bits. Note that we normally record data values in hex but our interface as we have designed it must be in decimal.

One of the problems with simply accessing that URL with a browser is that sometimes it will only work once. That is because your browser tries to cache the results. It will not actually access the URL again and thus the device is not triggered. There are some things we could do to the arduino sketch that would tell the browser not to cache the data and force it to fetch every time but from my research, there are a variety of methods to do that which may or may not always work. A simpler solution is instead of doing an HTML GET we can do an HTML PUT and not have to deal with the problem. Also from a theoretical point of view we are sending data to the device, so a PUT makes more sense than a GET. However to do a PUT we need a bit of fancy JavaScript. We can't just point our browser to a particular URL.

Before we talk about the JavaScript used to do the HTML PUT, let's take a peek at what that PUT command looks like when it is received by your board. Use the IoT_IR sketch with the SERIAL_DEBUG set to 1 and your serial monitor open. At line 47 there is a #if(0) that you should change to #if(1) to see what's really being sent. On your serial monitor you will see something like this.

""PUT /irsend/1/16582903/0/ HTTP/1.1
Accept: */*
Accept-Language: en-US
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like Gecko
Host: 192.168.1.131
Content-Length: 0
Connection: Keep-Alive
Cache-Control: no-cache

It is the job of the code in your Arduino sketch to capture this data using "client.readString()" or "client.read()" or "client.parseInt()" calls to extract the various parts of the URL. The main loop makes sure that it begins with "irsend" and then it calls the function "processIR(client)" to process the rest of the URL and get the protocol number, data value, an optionally number of bits.

In the next section we will talk about how we used JavaScript to create the HTML PUT command.

This guide was first published on Mar 12, 2018. It was last updated on Mar 12, 2018. This page (Understanding REST APIs) was last updated on Nov 11, 2019.