The HTTP RESTful API

This example uses the HTTP RESTful API to interact with the device using HTTP requests. Commands are sent to the device using HTTP REST methods such as GET and POST and a simple request syntax.

Using HTTP requests, you can send any command to the device and receive the response. The ZentriOS Web App offers a full demonstration of the HTTP RESTful API. This application note demonstrates how to use the basic requests of the RESTful API.

Other ways of managing and interacting with a ZentriOS device include:

This demo uses the following ZentriOS features:


This example demonstrates how to:


Setup

To run this example follow these steps:

Connect Your Device to the Local Network

Since you'll need to configure mDNS and the web server, the quickest way to setup the device is to use a ZentriOS terminal - see Getting Started. Once you have a terminal connected, issue the following command to configure the credentials for the local network:

> network_up -s

Enable the mDNS and HTTP Server

Enable mDNS and specify the domain the device will respond to using the following commands:

set mdns.enabled 1
set mdns.name mydevice

Enable the ZentriOS HTTP server and the RESTful API using the following ZentriOS commands:

set http.server.enabled     1
set http.server.api_enabled 1

Save the settings, then restart the network:

save
network_down
network_up

The device automatically starts the mDNS discovery service and the HTTP server on boot after connecting to the network.

The response from ZentriOS is similar to the following:

> Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.59
Starting mDNS
mDNS domain: mydevice.local
HTTP and REST API server listening on port: 80
[2015-01-15 | 23:48:42: Associated]

Syntax of REST API ZentriOS Commands

The format of a REST API ZentriOS command GET request is: GET http://mydevice.local/command/<command>

For example, to issue the ver command: GET http://mydevice.local/command/ver

To issue a GET request from a browser, enter the URL http://mydevice.local/command/ver into the browser URL address box.

The format of a REST API ZentriOS command POST request is: POST http://mydevice.local/command/<command> followed immediately by a json formatted structure of the form:

{
   "flags"   : <flags>,
   "command" : "<ZentriOS command>",
   "data"    : "<command data>"
}

The "data" value is required by commands that expect additional data sent immediately after the command, such as file_create. Some of the curl examples below demonstrate how to issue an HTTP POST request.

Sending Commands from a Web Browser

Using your favorite web browser (with a network client such as a PC, phone or tablet connected to the same local network as the device), enter the following URL to retrieve the ZentriOS version string, or click the following link if this computer is connected to the same network as the device: http://mydevice.local/command/ver

The browser responds with the ZentriOS version embedded in a JSON object, similar to the following text.

{"id":18,"code":0,"flags":0,"response":"ZentriOS-2.1.0.0, Built:2015-01-15 ... }

Troubleshooting

If you are having problems making this work, try the following


How does this work?

When the ZentriOS command is entered into the web browser address box, the browser translates the URL into an HTTP GET request and sends the request to the device name. The operating system in your PC (or phone / tablet) translates the device name into the device IP address and sends the request to the device. On the device, the HTTP web server receives and processes the request, and then provides a response back to the server.

A few more examples are shown below. For full documentation on the ZentriOS HTTP REST API, see Networking & Security, ZentriOS REST API.

Read a list of files on the device:

URLhttp://mydevice.local/command/ls
ZentriOS
Response
{"id":2,"code":0,"flags":0,"response":"! # Size Version Filename\r\n# 0 41741 2.1.0 command_help.csv\r\n# 1 135 2.1.0 default_setup.script\r\n# 2 1897 2.1.0 favicon.ico.gz\r\n# 3 1236 2.1.0 geotrust_ca.pem\r\n# 4 212736 2.1.0 sys/kernel.bin\r\n# 5 215204 2.1.0 sys/services.bin\r\n# 6 38004 2.1.0 ZentriOS_webgui.css.gz\r\n# 7 1827 2.1.0 ZentriOS_webgui.html\r\n# 8 61492 2.1.0 ZentriOS_webgui.js.gz\r\n# 9 210412 5.26.230 wifi_fw.bin\r\n"}

Read the raw value of the ADC connected to the thermistor on the Zentri Mackerel eval board or Moray eval board:

URLhttp://mydevice.local/adc 7 (Mackerel - GPIO 7)
http://mydevice.local/adc 20 (Moray - GPIO 20)
ZentriOS
Response
{"id":104,"code":0,"flags":0,"response":"0x835\r\n"}

Open a TCP connection to Google:

URLhttp://mydevice.local/command/tcp_client google.com 80
ZentriOS
Response
{"id":4,"code":0,"flags":0,"response":"0\r\n"}

Read the response to the TCP client connection above:

URLhttp://mydevice.local/log
ZentriOS
Response
{"logs":["HTTP and REST API server listening on port: 80","[2015-01-15 - 01:09:23: Associated]\r\n> ","Resolving host: google.com","[2015-01-15 - 01:28:53: Opening: google.com:80]","Connecting (TCP): 216.58.220.142:80","[2015-01-15 - 01:28:54: Opened: 0]"]}

Sending Commands Using JavaScript XMLHttpRequest

This demonstration uses POST requests. It is possible to send GET requests using XMLHttpRequest, but POST is more flexible. POST has no size restrictions, and the JSON data attribute allows additional data to be sent for ZentriOS commands such as file_create.

Download the demonstration HTML file js_rest_post.html.

This can be run directly as a file URL, provided you enable CORS for all domains on your device.

The following ZentriOS commands set up the device to work with the demonstration HTML page:

set wlan.ssid               <YOUR_SSID>
set wlan.passkey            <YOUR_PASSWORD>
set wlan.auto_join.enabled  1
set http.server.enabled     1
set mdns.name               mydevice
set mdns.enabled            1
set http.server.cors_origin *
save
reboot

Run the HTML file in a browser with the JavaScript developed console displayed. This shows errors that cannot be caught and displayed with the JavaScript try and catch mechanism.

You can run any ZentriOS command from this HTML. Just edit the request fields and click the Send POST Request button.

The demonstration JavaScript assembles the POST JSON from the request fields and makes an XMLHttpRequest to send the command to the device and display the response.

View the HTML source to see the JavaScript. The core of the demonstration is the sendPost() function.

For higher level access to the HTTP RESTful API via JavaScript, see ZentriOS JavaScript API.

Sending Commands Using cURL

Curl, a command line URL utility, may also be used to connect to the ZentriOS webserver. Curl is typically run from a PC or Linux command line for transferring data with a URL syntax. The following examples show how to use cURL with ZentriOS.

In some of the examples below, curl commands and response are shown in separate lines for readability purposes. Curl commands should be issued on a single command line.

Tip! If you are having trouble using curl, try using the -v verbose flag.

ZentriOS Version

Curl Command
curl http://mydevice.local/command/version
ZentriOS Response

Curl used with a URL only issues an HTTP GET request.

Verbose file list

This example reads a verbose list of files on the device and uses the more sophisticated POST request API. Note that the double-quotes may need to be escaped with backslash characters (as shown below) on some operating systems, such as Windows.

Curl used with the -d (--data) option issues an HTTP POST request. Note that the Content-Type header must be supplied to specify that the data posted is in json format.

Curl Command
curl -H "Content-Type: application/json" -d "" http://mydevice.local/command
ZentriOS Response
{"id":3,"code":0,"flags":0, "response":"! # Type Flags Hnd Size Version Filename\r\n # 0 e-FB 0001 82 41741 2.1.0.0 command_help.csv\r\n # 1 e-FD 0001 53 135 2.1.0.0 default_setup.script\r\n # 2 e-FE 0001 81 1897 2.1.0.0 favicon.ico.gz\r\n # 3 e-03 0001 52 1236 2.1.0.0 geotrust_ca.pem\r\n # 4 i-00 801B 0 212736 2.1.0.0 sys/kernel.bin\r\n # 5 i-81 801B 52 215204 2.1.0.0 sys/services.bin\ r\n # 6 e-FE 0001 55 38004 2.1.0.0 ZentriOS_webgui.css.gz\r\n # 7 e-FE 0001 54 1827 2.1.0.0 ZentriOS_webgui.html\r\n # 8 e-FE 0001 65 61492 2.1.0.0 ZentriOS_webgui.js.gz\r\n # 9 e-01 0009 0 210412 5.26.230.12 wifi_fw.bin\r\n"}

The value of the response key is the return data from the command. In this case it is the list of files. This is formatted to be read on a terminal in a monospace font, with new lines where each \r\n character sequence appears.

Open and Read a file

Open the default_setup.script file located on the ZentriOS file system:

Curl Command
curl -H "Content-type: application/json" -d "" http://mydevice.local/command
ZentriOS Response

The value of the response key is the return data from the command. In this case it is the stream number for the open file stream, 0, which is used as an argument to the stream_read command issued below.

Read the file using the stream_read command:

Curl Command
curl -H "Content-type: application/json" -d "" mydevice.local/command
ZentriOS Response

Change Log

ModifiedChangesZentriOS Version
Required
2015-02-03Created2.1+
2015-04-28Added JavaScript XMLHttpRequest Section2.1+