Representational state transfer (REST) is a software architecture style of the World Wide Web (WWW). This architecture is a set of constraints—client-server, statelessness, cacheability, layered system, code on demand, and uniform interface. These constraints improve the performance and scalability of web applications. For more details on REST architecture, refer to the following link:

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Once BeagleBone is connected to the Internet, it can communicate with servers on the Internet using protocols. Different protocols are defined to transfer different types of data. For example, the HTTP protocol was made for transferring and rendering HTML files. The SMTP protocol transfers e-mail. The SSH protocol gives a remote shell. Many online servers provide APIs to access their services via programs. Often this is done using custom protocol. If you want to access these services, there is a need for coding to call those APIs, for example Twitter provides APIs to access Twitter via an application. This is custom protocol implementation. This may or may not involve implementation of REST constraints. In our previous exercises, we did not follow REST constraints.

Another way of providing a web service is to use existing protocol. The most common protocol of the web is HTTP. It follows almost all the constraints of REST. So, if we implement our API over HTTP with uniform interface, we will be able to get the benefits of REST as standard. In that case, all our custom API request-response will be done over HTTP protocol. HTTP protocol has limited methods that can be called: GET/PUT/POST/DELETE. The standard way is to implement different APIs based on different resources. Each resource has a unique Uniform Resource Identifier (URI). Some URIs are reserved for API communication instead of a HTML page. When the HTTP method is called on these URIs, an API response is given instead of an HTML page. Actions are performed based on location requested, for example if the client calls the POST method on URI http://api.example.com/member1/item17, the server will create Item17 as a new entry for member1. URIs are arranged in a uniform hierarchical way so that they are easy to manage. Learning different URIs is easier than learning custom APIs. Porting to other languages and platforms becomes easier as you are accessing HTTP links only. Also, you do not to have special software for testing. You can execute a few APIs from the client web browser. This will be clearer when you go through the next exercise. REST uses fewer resources, which is important for embedded systems.

Many popular IoT web services provide REST APIs to access them. We are going to use one such a web service later in this chapter. Let's write a small program that will provide a REST API to a client. If a remote web browser calls http://<beaglebone IP>/servo/angle/<number>, then it should change the angle of the servo motor attached to BeagleBone. There is no HTML file needed for this exercise. Attach a micro servo motor like we did in Chapter 6, PWM – Writing Analog Information. Create a new file with the name flask_servo.py inside the Cloud9 IDE and write the following code in it. Save and run the program. Then open the web browser from your connected smartphone/computer. Put this address in the address bar: http://<Beaglebone's IP address> :3002/servo/angle/90. You should be able to see movement in the servo motor and the text angle changed to 90 appears in the web browser. You can try any angle between 0 and 180. The code for flask_servo.py is as follows:

import Adafruit_BBIO.PWM as PWM
from flask import Flask, render_template
app = Flask(__name__)

servo = "P9_14"
PWM.cleanup()
PWM.start(servo, 0, 60)
duty_min = 3

@app.route('/servo/angle/<angle>')
def change_angle(angle):
    angle = float(angle)
    print angle
    if (angle < 0) or (angle > 180):
        return "Invalid input"
    print (angle * 0.064) + duty_min
    PWM.set_duty_cycle(servo, (angle * 0.064)+ duty_min)
    return "angle changed to " + str(angle)

app.run('0.0.0.0', 3002)