HTTP(S)

The HTTP module is an interface to the HTTP stack located on the GM02S modem. It is implemented as a Also called the "Singleton Pattern".Singleton Class, meaning there can only be one instance of it. Singleton allows direct calls, for instance HttpClient.configure(URL, 80, false).

Both HTTP and HTTPS are supported. Available methods are GET, POST, PUT, DELETE, and HEAD.

Example​

// Start up the LEDs and display a start up animation
LedCtrl.begin();
LedCtrl.startupCycle();

// Start the logging system to get messages logged
Log.begin(115200);

// Initialize the LTE Modem and connect to the network
Lte.begin();

// Configure the HTTP client to connect to URL
// If we want to use HTTPS we change the port and 
// the boolean to true, e.g. HttpClient.configure(URL, 443, true);
HttpClient.configure(URL, 80, false);

// Perform a GET request to URL/URI
HttpClient.get(URI);

// Read and print out the resulting body
Log.infof("%s", HttpClient.readBody());

Initialization & Dependencies​

• The LTE module must be initialized
• HttpClient.configure() must be called at least once

Sending a Request​

Every supported HTTP method has a corresponding call to the HttpClient object, such as HttpClient.get() and HttpClient.post(). All of these calls take an endpoint argument and a payload. The payload can either be a C-String or a pointer to a buffer with a given size. On every request, a HttpResponse object is returned, with the status code and the data size of the body.

It is advised to check that the status code is 200 (STATUS OK) after a request.

if(HttpClient.get(URI).status_code == HttpClient.STATUS_OK) {
    // The request was successful
}

Headers and Content Type​

All requests can also have an HTTP header. They are optional arguments passed after the URL for GET, HEAD and DEL and after the message for POST and PUT. They can be used in the following way: HttpClient.post(URL, "test data", "<header>", HttpClient.CONTENT_TYPE_TEXT_PLAIN). Please refer to the example Arduino sketch https_with_headers for more information and the HttpClient API reference.

POST and PUT calls can also have a content type, which has to be passed after the header in the following way: HttpClient.post(URL, "test data", "<header>", HttpClient.CONTENT_TYPE_TEXT_PLAIN).

Status Codes​

The HTTP module will report two types of status codes. Both can be found in the returned HttpResponse structure from each of the respective requests (see the HTTP API):

1. curl status codes
2. HTTP status codes

The curl status codes are related to the connection itself, not necessarily the HTTP layer. If an HTTP request is sent to a domain that does not exist, a curl error will be raised concerning that the library failed to resolve the host of the domain. HTTP error codes are related to the HTTP layer itself, such as 404 for resource not found and 500 for internal server error.

Reading the Response Body​

Upon a successful request, the response body is stored in a buffer. There can only be one response body in the buffer at any given time. All subsequent requests overwrite the previous request. The buffer can be accessed through HttpClient.readBody().

if(HttpClient.get(URI).status_code == HttpClient.STATUS_OK){
    // Option 1: Read the buffer as an Arduino String
    String body = HttpClient.readBody();  // Reads up to 256 bytes
    Log.info(body);

    // Option 2: Read the buffer to a C-String
    uint8_t buffer[256];
    HttpClient.readBody(buffer, 256);
    Log.info(buffer);
}

Example (Interactive)​

Use the interactive code editor to compile a hex file that you can program onto your board. Everything except for the HTTP Client has already been configured.

Live Editor​

Serial Terminal​