Skip to main content

HTTP(S)

note

For an API reference, see API Reference/HTTP

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.

caution

Using HTTPS requires a security profile to be set up on the board. This only has to be done once. Run the example sketch called provision from the Arduino IDE and you will be guided through the process in the serial terminal.

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

caution

Remember to connect the Antenna to the board before running any examples that use a wireless feature (i.e. LTE, MQTT) or web service (i.e. AWS, HTTP)

  • 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

Live Editor
if (!HttpClient.configure("worldtimeapi.org", 80, false))
{
Log.errorf("Failed to configure the http client for the domain %s\r\n", "worldtimeapi.org");
return;
}
Log.info("Configured to HTTP");
HttpResponse response = HttpClient.get("/api/timezone/Europe/Oslo.txt");
if (response.status_code != HttpClient.STATUS_OK)
{
Log.error("Error when performing a GET request");
return;
}
String body = HttpClient.readBody(512);
Log.infof("%s\r\n", body.c_str());
 
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
No action performed

Serial Terminal

Unsupported Browser
Your browser does not support the online serial terminal. Supported browsers are Google Chrome, Microsoft Edge and Opera.