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 works for any board with a Gecko OS device. This assumes the module is configured the default factory settings.

Open a Gecko OS 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 Gecko OS device.

> python get_post_server.py test

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 Gecko OS 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 Gecko OS terminal, enter the following command sequence:

Gecko OS 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 - - [01/Jan/2019 12:05:18] "GET / HTTP/1.1" 200 -

The Gecko OS terminal output is similar to the following:

> http_get http://10.5.6.60:8000
[2019-01-01 | 02:05:21: Opening: http://10.5.6.60:8000]
Request GET /
Connecting (http): 10.5.6.60:8000
[2019-01-01 | 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:

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

[2019-01-01 | 02:05:21: Closed: 0]

Note that Gecko OS 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:

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

The Gecko OS terminal output is similar to the following:

> http_get http://10.5.6.60:8000/?class=amphibia&color=green&name=kermit
[2019-01-01 | 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
[2019-01-01 | 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.

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

The Gecko OS terminal output is similar to the following:

> http_get -o http://<Server IP>:8000/?class=amphibia&color=green&name=kermit
[2019-01-01 | 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
[2019-01-01 | 04:24:50: Opened: 0]
0

Note that the Gecko OS 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:

http_add_header 0 x-weather sunnyday

The Gecko OS 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:

http_read_status 0

The request is now completed and sent. The Gecko OS 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:

read 0 1000

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

[2019-01-01 | 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.

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 Gecko OS terminal output is similar to the following:

> http_post -o http://10.5.6.60:8000 application/json
[2019-01-01 | 07:55:23: Opening: http://10.5.6.60:8000]
Request POST /
Connecting (http): 10.5.6.60:8000
[2019-01-01 | 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"
}

[2019-01-01 | 07:55:25: Closed: 0]

Sending an HTTP POST Request without Chunking

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 Gecko OS terminal output is similar to the following:

> http_post -l 72 http://10.5.6.60:8000 application/json
[2019-01-01 | 08:15:12: Opening: http://10.5.6.60:8000]
Request POST /
Connecting (http): 10.5.6.60:8000
[2019-01-01 | 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"
}

[2019-01-01 | 08:15:14: Closed: 0]

Supporting Gecko OS Versions

• Gecko OS 4

Change Log