The HTTP RESTful API

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

Using HTTP requests, you can send any command to the module and receive the response. The WiConnect 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 an ACKme module include:

• WiConnect Terminal - via physical connection to USB port (see Getting Started, Opening a WiConnect Terminal)
• Wi-Fi Remote terminal - Telnet connection via Wi-Fi ( see Wi-Fi Remote Terminal application note.
• For more sophisticated scripting, the WiConnect JavaScript API provides a JavaScript wrapper around the HTTP server REST API
• A WiConnect Python API providing a Python wrapper around the HTTP server RESTful API. See wiconnectpy.

This demo uses the following WiConnect features:

• mDNS discovery - to make it easy to find the module on the local network. See Networking and Security, Network Discovery.
• WiConnect RESTful API - for executing WiConnect commands directly via HTTP requests. See Networking and Security, HTTP server with RESTful API

This example demonstrates how to: - Setup the module to connect to your local network - Start the WiConnect mDNS service and HTTP web server - Use a web browser, JavaScript or cURL to send commands to the module, and receive responses from WiConnect

Setup

To run this example follow these steps:

Connect Your Module to the Local Network

Since you'll need to configure mDNS and the web server, the quickest way to setup the module is to use a WiConnect 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 module will respond to using the following commands:

set mdns.enabled 1
set mdns.name mymodule

Enable the WiConnect HTTP server and the RESTful API using the following WiConnect 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 module automatically starts the mDNS discovery service and the HTTP server on boot after connecting to the network.

The response from WiConnect is similar to the following:

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

Syntax of REST API WiConnect Commands

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

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

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

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

{
   "flags"   : <flags>,
   "command" : "<wiconnect 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 module), enter the following URL to retrieve the WiConnect version string, or click the following link ver if this computer is connected to the same network as the module:

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

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

Troubleshooting

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

• omit the .local domain in the URL, and use http://mymodule/command/ver instead.
• replace mymodule.local with the IP address of the module (available by reading the WiConnect IP address variable get network.ip). The issue may be related to the operation of mDNS which has some operating system caveats. See Networking & Security, Network Discovery

How does this work?

When the WiConnect 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 module name. The operating system in your PC (or phone / tablet) translates the module name into the module IP address and sends the request to the module. On the module, 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 WiConnect HTTP REST API, see Networking & Security, WiConnect REST API.

Read a list of files on the module:

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

Open a TCP connection to Google:

Read the response to the TCP client connection above:

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 WiConnect 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 module.

The following WiConnect commands set up the module 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               mymodule
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 WiConnect 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 module 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 WiConnect JavaScript API.

Sending Commands Using cURL

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

In some cases, the arguments to curl in the examples below have been put onto separate lines for readability purposes only. Curl commands should be issued on a single command line.

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

WiConnect Version

$> curl http://mymodule.local/command/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 module 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 -H "Content-Type: application/json"
        -d "{\"flags\":0,\"command\":\"ls -v\"}"
        http://mymodule.local/command

|

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 WiConnect file system:

$> curl -H "Content-type: application/json"
        -d "{\"flags\":0,\"command\":\"file_open default_setup.script\"}"
        http://mymodule.local/command

|

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 -H "Content-type: application/json"
        -d "{\"flags\":0,\"command\":\"stream_read 0 300\"}"
        mymodule.local/command

|

Change Log