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 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 Gecko OS device include:

• Gecko OS Terminal - via physical connection to USB port (see Getting Started, Opening a Gecko OS Terminal)
• Wi-Fi Remote terminal - Telnet connection via Wi-Fi (see Wi-Fi Remote Terminal application note). {*
• For more sophisticated scripting, the Gecko OS JavaScript API provides a JavaScript wrapper around the HTTP server REST API *}

This demo uses the following Gecko OS features:

• Gecko OS RESTful API - for executing Gecko OS commands directly via HTTP requests. See Networking and Security, HTTP server with RESTful API.

This example demonstrates how to:

• Setup the device to connect to your local network
• Start the Gecko OS HTTP web server
• Use a web browser, JavaScript or cURL to send commands to the device, and receive responses from Gecko OS

Setup

To run this example follow these steps:

Connect Your Device to the Local Network

Since you'll need to configure the web server, the quickest way to setup the device is to use a Gecko OS 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 HTTP Server

Enable the Gecko OS HTTP server and the RESTful API using the following Gecko OS 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 HTTP server on boot after connecting to the network.

The response from Gecko OS is similar to the following:

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

Note the reported device IPv4 address for later substition for <Device IP Address>.

Syntax of REST API Gecko OS Commands

The format of a REST API Gecko OS command GET request is: GET http://<Device IP Address>/command/<command>

For <Device IP Address> substitute the IP address reported by Gecko OS when the network came up.

For example, to issue the ver command: GET http://<Device IP Address>/command/ver

To issue a GET request from a browser, enter the URL http://<Device IP Address>/command/ver into the browser URL address box.

The format of a REST API Gecko OS command POST request is: POST http://<Device IP Address>/command/<command> followed immediately by a json formatted structure of the form:

{
   "flags"   : <flags>,
   "command" : "<Gecko OS 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 Gecko OS version string, or click the following link if this computer is connected to the same network as the device:

http://<Device IP Address>/command/ver

For <Device IP Address> substitute the IP address reported by Gecko OS when the network came up.

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

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

How does this work?

When the Gecko OS 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 Gecko OS HTTP REST API, see Networking and Security, HTTP server with RESTful API.

Read a list of files on the device:

Open a TCP connection to Google:

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 Gecko OS 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 Gecko OS 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 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 Gecko OS 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.

Sending Commands Using cURL

Curl, a command line URL utility, may also be used to connect to the Gecko OS 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 Gecko OS.

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.

Gecko OS Version

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.

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 Gecko OS file system:

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:

Supporting Gecko OS Editions and Versions

• Gecko-OS-2.0+

Change Log