Using the HTTP GET and HTTP POST Commands

Description

This application note describes the procedure for using the http_get and http_post commands.

Setup

This demonstration uses an ACKme Mackerel evaluation board, but it works for any board with an ACKme WiConnect module. This assumes the module is configured the default factory settings.

Open a WiConnect terminal to the module and configure the module to connect to your local network as follows:

set wlan.ssid               <YOUR SSID>
set wlan.passkey            <YOUR PASSWORD>
set wlan.auto_join.enabled  1
save
reboot

Download the HTTP Get and POST server python script: get_post_server.py (Python 2.7).

This HTTP server responds to a GET or POST request with a plain text report on the request details. The server also outputs details of each request on stdout.

Run the server in a terminal on a computer connected to the same network as the WiConnect module. The output is similar to the following:

> get_post_server.py
Serving at: http://localhost:8000
<Server IP>: 10.5.6.60

Note the local IP address of the computer running the server. Depending on the server computer configuration, the python script may display the local IP address correctly (shown as 10.5.6.60 above). However if 127.0.0.1 or similar is displayed, use another method to obtain the server local IP address. This needs to be substituted for the symbol <Server_IP> in the WiConnect command sequences below.

Sending a Simple GET Request

The simplest way to use http_get command is to specify only a URL. The response returns a stream ID.

This is similar to the request shown in Getting Started, Verifying the Internet Connection. However our test server script returns a report on the request details, rather than the requested web page.

In the WiConnect terminal, enter the following command sequence:

WiConnect Commands	Description
`http_get http://<Server IP>:8000`	`Send GET request to specified URL`

WiConnect sends the request immediately.

The get_post_server.py output is similar to the following:

------------------------------------
# Processing GET Request
## Client
10.5.6.108:61905
## Headers
Host: 10.5.6.60
Accept-Encoding:
Connection: Close

## Request
/
10.5.6.108 - - [30/Apr/2015 12:05:18] "GET / HTTP/1.1" 200 -

The WiConnect terminal output is similar to the following:

> http_get http://10.5.6.60:8000
[2015-04-30 | 02:05:21: Opening: http://10.5.6.60:8000]
Request GET /
Connecting (http): 10.5.6.60:8000
[2015-04-30 | 02:05:21: Opened: 0]
HTTP response: 200
Status: 200
0

The stream handle is returned as the last line of the response. In all these examples, we assume the stream handle is 0. This implies that you have closed all open streams before proceeding to the next example. List open streams with stream_list. Close all open streams with the close all command.

Now you can read the data from the stream until there is nothing left to read:

WiConnect Commands	Description
`read 0 1000`	`Read up to 1000 characters from the stream returned in the response to http_get`

The WiConnect terminal output is similar to the following:

> read 0 1000
GET Request

----
You sent these headers:
Host: 10.5.6.60
Accept-Encoding:
Connection: Close

You sent no query.

[2015-04-30 | 02:05:21: Closed: 0]

Note that WiConnect has closed the stream, as it came to the end of the stream after reading less than the 1000 characters specified.

Reading the HTTP Status Code

You may wish to determine whether the request was successful before attempting to read the stream, using the http_read_status command. Software running on a host MCU can read the response and take action depending on its value. In our manual demonstration, we ignore the status code response and continue with a read immediately.

We also add a query to the URL to demonstrate how the test server responds to a query:

WiConnect Commands
`http_get http://<Server IP>:8000/?class=amphibia&color=green&name=kermit http_read_status read 0 1000`

The WiConnect terminal output is similar to the following:

> http_get http://10.5.6.60:8000/?class=amphibia&color=green&name=kermit
[2015-04-30 | 04:10:50: Opening: http://10.5.6.60:8000/?class=amphibia&color=green&name=kermit]
Request GET /?class=amphibia&color=green&name=kermit
Connecting (http): 10.5.6.60:8000
[2015-04-30 | 04:10:50: Opened: 0]
HTTP response: 200
Status: 200
0
> http_read_status 0
200
> read 0 1000
GET Request

----
You sent these headers:
Host: 10.5.6.60
Accept-Encoding:
Connection: Close

You sent this query:
class=amphibia&color=green&name=kermit

Sending a GET Request with Custom Headers

You may wish to send custom headers as part of your GET request. To do this, use the -o option with the http_get command.

This defers sending the request and leaves the stream open.

WiConnect Commands
`http_get -o http://<Server IP>:8000/?class=amphibia&color=green&name=kermit`

The WiConnect terminal output is similar to the following:

> http_get -o http://10.5.6.60:8000/?class=amphibia&color=green&name=kermit
[2015-04-30 | 04:24:49: Opening: http://10.5.6.60:8000/?class=amphibia&color=green&name=kermit]
Request GET /?class=amphibia&color=green&name=kermit
Connecting (http): 10.5.6.60:8000
[2015-04-30 | 04:24:50: Opened: 0]
0

Note that the WiConnect terminal displays no HTTP status response, and the test server does not show output for this request, because it has not yet been sent.

Now you can add a custom header using the http_add_header command:

WiConnect Commands
`http_add_header 0 x-weather sunnyday`

The WiConnect terminal responds with Success, but does not yet send the request. You can add more headers if you wish.

To complete the request, use the http_read_status command:

WiConnect Commands
`http_read_status 0`

The request is now completed and sent. The WiConnect terminal output shows an HTTP status code:

> http_read_status 0
HTTP response: 200
200

The test server output shows that the request was received and processed.

You can now read the server response:

WiConnect Commands
`read 0 1000`

The WiConnect terminal response is similar to:

> read 0 1000
GET Request

----
You sent these headers:
Host: 10.5.6.60
Accept-Encoding:
x-weather: sunnyday
Connection: Close

You sent this query:
class=amphibia&color=green&name=kermit

[2015-04-30 | 04:31:36: Closed: 0]

Note that the server received and reported the custom header.

Sending a POST Request

To send a POST request, use the http_post command. You must specify the mime-type of the content.

To send any post content, you have to use the -o option to defer sending the post until http_read_status is called.

Then write the POST content to the stream, specifying the length.

You can send custom headers using the http_add_header command.

The http_read_status command completes the POST request and responds with the HTTP status code.

You can the read the HTTP response with the stream_read command.

WiConnect Commands Description

WiConnect Commands	Description
`http_post -o http://<Server IP>:8000 application/json http_add_header 0 x-weather cloudsaway write 0 72 { "class":"amphibia", "color":"green", "name":"kermit" } http_read_status 0 read 0 1000`	`Post with the -o option to defer request Add a custom header Write POST content to the stream Complete and send the request Read up to 1000 characters from the stream`


http_post -o http://<Server IP>:8000 application/json
http_add_header 0 x-weather cloudsaway
write 0 72
{
    "class":"amphibia",
    "color":"green",
    "name":"kermit"
}
http_read_status 0
read 0 1000


Post with the -o option to defer request
Add a custom header
Write POST content to the stream





Complete and send the request
Read up to 1000 characters from the stream

Note that in the write command in this example, the length specified assumes that the lines of the POST content are terminated with CR-LF (2 characters).

Note that the default http_post behavior is to chunk the data. The header Transfer-Encoding: chunked is sent. You can use the -l option to send the content all in one piece, specifying the length.

The WiConnect terminal output is similar to the following:

> http_post -o http://10.5.6.60:8000 application/json
[2015-04-30 | 07:55:23: Opening: http://10.5.6.60:8000]
Request POST /
Connecting (http): 10.5.6.60:8000
[2015-04-30 | 07:55:23: Opened: 0]
0
> http_add_header 0 x-weather cloudsaway
Success
> write 0 72
{
    "class":"amphibia",
    "color":"green",
    "name":"kermit"
}
Success
>
Ready
> http_read_status 0
HTTP response: 200
200
> read 0 1000
POST Request

----
You sent these headers:
Host: 10.5.6.60
Accept-Encoding:
Transfer-Encoding: chunked
Content-Type: application/json
x-weather: cloudsaway
Connection: Close

You POSTed this content:
{
    "class":"amphibia",
    "color":"green",
    "name":"kermit"
}

[2015-04-30 | 07:55:25: Closed: 0]

Sending an HTTP POST Request without Chunking

WiConnect Commands Description

WiConnect Commands	Description
`http_post -l 72 http://10.5.6.60:8000 application/json http_add_header 0 x-weather cloudsaway write 0 72 { "class":"amphibia", "color":"green", "name":"kermit" } http_read_status 0 read 0 1000`	`Post with the -l <length> option to defer request Add a custom header Write POST content to the stream Complete and send the request Read up to 1000 characters from the stream`


http_post -l 72 http://10.5.6.60:8000 application/json

http_add_header 0 x-weather cloudsaway
write 0 72
{
    "class":"amphibia",
    "color":"green",
    "name":"kermit"
}
http_read_status 0
read 0 1000


Post with the -l <length> option
  to defer request
Add a custom header
Write POST content to the stream





Complete and send the request
Read up to 1000 characters from the stream

Note that the header Content Length:72 is sent. The -l length is the length of the POST content only, the same as is specified for the write command.

The WiConnect terminal output is similar to the following:

> http_post -l 72 http://10.5.6.60:8000 application/json
[2015-04-30 | 08:15:12: Opening: http://10.5.6.60:8000]
Request POST /
Connecting (http): 10.5.6.60:8000
[2015-04-30 | 08:15:12: Opened: 0]
0
> http_add_header 0 x-weather cloudsaway
Success
> write 0 72
{
    "class":"amphibia",
    "color":"green",
    "name":"kermit"
}
Success
>
Ready
> http_read_status 0
HTTP response: 200
200
> read 0 1000
POST Request

----
You sent these headers:
Host: 10.5.6.60
Accept-Encoding:
Content-Type: application/json
Content-Length: 72
x-weather: cloudsaway
Connection: Close

You POSTed this content:
{
    "class":"amphibia",
    "color":"green",
    "name":"kermit"
}

[2015-04-30 | 08:15:14: Closed: 0]

Change Log

Modified	Changes	WiConnect Version Required
2015-04-30	Created	1.0+