Interface With RestServer As a Client

What is REST: REST stands for Representational State Transfer and refers to a software and system architecture that is widely used on the web today. I am not going to attempt to describe what it means here as there is a wealth of articles and resources on the internet that have already done so. In case you are interested in learning more about it the wikipedia entry is a good starting point.

Support for GET and POST Requests:

The RestServer library supports GET and POST http requests. Due to length of these requests (you can see an example of a POST request below) and the RAM limitations of the Arduino platform this library can only provides a limited amount of functionality compared to RESTful services hosted on more powerful servers and computers. Therefore, here I will provide an overview of how the RestServer library parses these requests so that you can interface effectively with devices running the RestServer library.

POST /input_4 HTTP/1.1
Host: 192.168.2.200:7999
Connection: keep-alive
Content-Length: 10
Cache-Control: max-age=0
Origin: http://192.168.2.200:7999
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.2 (KHTML, like Gecko) Chrome/15.0.874.121 Safari/535.2
Content-Type: application/x-www-form-urlencoded
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Referer: http://192.168.2.200:7999/input_4/32
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3

input_4=43

Reading and Parsing GET Requests:

When processing a GET request the RestServer library only reads the request verb and the request URI. Both of these elements are included in the first line of a HTTP request. Therefore, the request verb is used to identify the start of new request.

When a GET request is identified, the RestServer reads the entire first line of the request. The server transitions to parsing the request when it reaches a carriage return followed by a line feed. All other information associated to the request is discarded (this is not the case for POST requests, as you will see shortly).

http://your_device_address/temp  // resource address in browser
GET /temp HTTP/1.1    // first line of a GET request received by your device
GET /temp             // content captured by RestServer for parsing

In the example above the URI specifies that this is a request for a resource named temp. If the device has a resource with that name it will return an html or json document featuring the current state of that resource. If this resource can be updated and the response format is set to html then this document will also contain a form that can be used to update the resource's state.

http://your_device_address/temp/humidity/light  // resource request chaining

RestServer supports chaining multiple resources in a single request. When resources are chained in this manner the response will feature the state of all available resources, and all update capable resources will be featured in the form.

GET Request Options:

When the POST_WITH_GET option is enabled, you can use get requests to update resources. In the example below, the state of a resource named "light" is being set to 1. Please note that this goes against RESTful best practices, so by default it is disabled. That said, this is a useful capability to use when working with json format, since no forms are rendered in json requests.

http://your_device_address/light/1    // updating resources with get requests

There are some special cases and keywords that can be used in your requests. First, if you do not specify any resources then RestServer will respond with the state of all available resources. Next, if you precede your resource requests with the keyword json then the response will be returned in json format.

http://your_device_address/           // returns all resource states
http://your_device_address/json       // returns all resource states in json format
http://your_device_address/json/temp  // returns temp resource state in json format

Lastly, if you make a request for /resource_info then the RestServer will return a description of each resource available on the device. The description will include a resource's name, information about whether the resource can be updated, and the range of the resource. Responses to this request are only provided in json format.

http://your_device_address/resource_info

// sample response to resource_info request
[
	{
		'resource_name':'output_1',
		'post_enabled':'false',
		'range':{'min':0,'max':1024}
	},{
		'resource_name':'output_2',
		'post_enabled':'false',
		'range':{'min':0,'max':1024}
	}
]  

Reading and Parsing POST Requests:

Now let's turn our attention to the processing of POST requests. These types of request are processed differently than GET requests because the resources being requested are featured in the request's body, rather than the request's URI. Just take a look at the sample POST request featured at the top of this page. As you will note, the request verb is in the same location as in a GET request, but the resource update description is located in the body of the request.

The RestServer uses the request verb to identify new requests. Once a request has been identified it searches for the "Content-Length:" attribute in order to determine how many characters should be read from the body of the request. Then the RestServer looks for the end of the request header as way to identify the beginning of the request body. The end of the header is identified by and end of line sequence that is repeated twice (carriage return followed by line feed).

With this in mind, below is an example of the simplest possible POST request that can be parsed by the RestServer. As you will note this request features all of the attributes I described above.

POST /input_4 
Content-Length: 10

input_4=43  

The forms that are rendered in response to GET requests that feature update-capable resources generate POST requests similar to the one at the top of this page. These forms provide an easy way to update resources from a browser session. The only other way to update resources from a browser session is to activate the POST_WITH_GET option so that you can send update embedded in the URI.