HTTP(S)
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.
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
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):
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.