Home / Tutorials / ESP32 Tutorial / Using RESTful APIs with ESP32
ESP32 NodeMCU-32S

Using RESTful APIs with ESP32

With its WiFi capabilities, the ESP32 can connect to API services and acquire useful (and sometimes useless) information from the web. Here’s a quick tutorial on how to connect to RESTful APIs using ESP32.

What is RESTful API

A RESTful API is an architectural style for exchanging information between servers typically using, but not exclusively, HTTP requests.

In Introduction to HTTP Basics
HTTP Request. Image from Chua Hock-Chua

A client like a web browser normally uses HTTP requests when requesting data from a server. However, RESTful APIs make it much simpler as the requesting client only uses an URL specifying the requested resources to which the server responds.

Setup

For this tutorial, I am using the Chuck Norris API which gives jokes about the famous action movie icon. The jokes (resource) are retrieved using GET requests through the URL: https://api.chucknorris.io/jokes/random.

The libraries I am using are the HTTPClient and ArduinoJson libraries. The HTTPClient is already included in the ESP32 core for Arduino.

To install the ArduinoJson library, go to Sketch ->  Include Library -> Manage Libraries in the Arduino IDE. Then type "ArduinoJSON" in the search field. The first search result is the library we need.

Much of the code here is from the WiFiClient example sketch and just modified to read the response from the API. Naturally, we must first establish a connection to the Internet. This is done by including this line inside the setup() routine:

The variables ssid and password are both char array pointers declared just before setup() routine. For example, if your WiFi’s ssid is “Chuck” and your password is “Norris” then this is how you would declared them (again, outside or before setup());

Next start connecting to the WiFi and wait until it’s connected. Here’s the code for that:

Once connected, you can now send an API request using the HTTPClient library. Create a HTTPClient object like this:

Other APIs need additional headers for the request. To do that, just use the addHeader function. For example:

But for the Chuck Norris API, we don’t need additional headers so we skip these two lines. The only thing we need now is to execute the request.

The API request is executed through the following lines:

Then we wait for the API’s response:

Parsing the Response

The API will send a response similar to this:

This is a JSON array which contains a number of information. What we want for now is to get the joke. That would be the value of the key “value”.

To extract this part of the response, we need the ArduinoJSON library.

The library requires a JSON document with specific size.

You can go to https://arduinojson.org/v6/assistant/ and paste an example JSON output from an API to know the correct size. However, it’s safer to just use a large number to cater API responses with varying lengths.

Next, we parse the JSON string:

The code above returns an error if the parsing failed. Errors are listed on https://arduinojson.org/v6/api/misc/deserializationerror/

Finally, we extract our target information using:

To close the connection, we end the code with

ESP32 Chuck Norris Full Code

Here’s the full code:

To view the Chuck Norris joke, just open the Arduino IDE’s serial monitor.

APIs with SSL

If your API of choice has added security like SSL, there are a few things you need to do.

First, download OpenSSL and install on your computer.

Then, issue the following command:

Here, the API url is strictapithatrequireshttps.com. Change this to match your API.

Out of the many outputs of this command is the SSL certificate. It starts with

and ends with

Copy the certificate, paste it on a text editor and save it as cert.perm. It’s easier if the location of this cert.perm is the same location as your current CMD directory.

Then, issue this command in openssl:

This reads out the SHA1 from the certificate which we’ll need to add in our code/sketch. For example, the output of this command would be:

In the code, we add the SHA1 code in our http.begin() statement. Remember to replace the colons with a space.

You should now be able to use the API just like the first example.

Check Also

ESP32 Web Server

Sensor Display on ESP32 Web Server

Last time, I showed you how to setup the ESP32 development board with the Arduino …

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.