This is the third part of a series of posts about building an Internet of Things (IoT) server with flask, Python and ESP8266 microcontrollers. In the last post, we reviewed server and hardware setup. In this post, we'll build a web API with flask and push temperature data to our web API with a web browser.
We already have a working flask app hosted on Digital Ocean. Now we need to add a web API to the flask app's functionality.
What is a web API?
A web API is a web-based Application Programming Interface. That's a fancy way of saying a server that saves input or produces output based on a URL the server recieves from a web browser.
An example of a web API is the ThingSpeak.com web API. When a web browser, like chrome, is directed to the followoing URL:
The response is a data entry stored on ThingSpeak.com that corresponds to:
- channel 266256
- field 2
- last entry
- .txt format
If the URL pasted into the web browser is different, ThingSpeak.com's response will also be different.
The response to the URL above is a data entry stored on ThingSpeak.com that corresponds to:
- channel 9
- field 1
- last entry
- .json format
Most web API's allow you to pull data off of their servers, but many web API's also give you the ability to put data up on their servers.
If the URL pasted into the web browser is constructed in the format below, ThingSpeak.com will store a new data point.
The datapoint ThingSpeak.com stores when it recieves the GET request is:
- user with an API Key = THECLASSAPIKEY
- field = 1
- data = 87
The web API we'll build with flask needs to fullfill the same two basic functions the ThingSpeak.com web API accomplishes:
- Output a data point based on the particular URL the flask IoT server receives
- Store a data point based on the particular URL the flask IoT server receives
Web API Design
We're going to mimic part of the ThingSpeak.com web API in our flask IoT server web API. In order to store a data point based on the URL the server recieves, we need to specify how the URL must be structured. Our ESP8266-based WiFi weather stations need to know the URL format in order to post data points on the flask IoT server.
Data will be stored on our flask IoT server based on the URL the server recieves from the ESP8266-based WiFi weather stations.
There are a couple unique aspects to each of the ESP8266-based WiFi weather stations:
- a user: Each WiFi weather station has a user. In this case the user is me.
- a mac address: A mac address is a unique address assigned to each piece of hardware. Each of the ESP8266-based WiFi weather stations has a different mac address.
- field: The ESP8266-based WiFi weather stations have the capability to output temperature and humidity. Right now we are just going to deal with temperature, but it would be nice to have an extra field available for multiple data streams (like temperature and humidity) from the same device.
- data: The temperature measurement which comes out of each ESP8266-based WiFi weather station.
If we put these 4 identifiers as part of our web API URL, our IoT server will provide the functionality the WiFi weather stations need.
The general form of our web API URL is below:
In the URL above we've provided:
update(to tell the IoT server to save the data point, not just serve a webpage)
API_key=ASCIISTR(to identify the user)
mac=6c:rf:7f:2b:0e:g8(to identify the ESP8255-based WiFi weather station)
field=1(to specify the data is a temperature, not humidity)
data=72.3(to specify the temperature is 72.3 degrees)
Now we need to make our flask IoT server save the data point when a URL like the one we specified above comes in.
Construct a flask web API
Building web API's in flask is pretty easy due to flask's option of including a variable in a route. The general syntax is below:
@app.route("/update/key=<route_var>", methods=['GET']) def update(route_var): # code to run return render_template("index.html")
In the code above, the route
"/update/key=<route_var>" has a the variable
<route_var> contained in it. The greater than/less than symbols
< > tell flask there is a variable in the route. In the second line, the variable
route_var (which came in from the
@app.route() line) is passed as an argument to the
update() function. Finally, the
update() function returns a tempate called
Create a new route
There are four variables to assign in the
@pp.route() URL of our flask web API:
|API key||unique identifier each user||
|mac address||unique identifier for each ESP8266 device||
|field||denote temperature or humidity||
|data||data point to save on the server||
@pp.route() URL for our web API looks like:
We can now build a new
@app.route()-function pair for this URL. Note we return a new template called update.html and pass the template the data point
@app.route("/update/API_key=<api_key>/mac=<mac>/field=<int:field>/data=<data>", methods=['GET']) def update(api_key, mac, field, data): return render_template("update.html", data=data)
Create a new template
Since we are calling a new template, we need to construct a new template. The template update.html can have the same form as index.html. Let's create a new file and copy in the following html code and jinja fields.
$ cd ~ $ cd flaskapp $ cd templates $ nano update.html
The code for the new update.html template is below:
Test the web API
Now on our server, we can restart the flask app and see if our web API works.
$ sudo systemctl start flaskapp $ sudo systemctl status flaskapp # [ctrl-c] to exit.
If we browse to the web address of the server, we should still see the same index template rendered.
But now if we go to the web address:
You see the update tempate rendered with a temperature of
It works! When we put a specific URL into our web browser, it causes the temperature we see on the web to change.
In the next post, we'll modify our flask IoT server to do some validation of the input from the web API. We don't want just any person to bang away at the API and upload data points. We are also going to delve into Python's datetime module and add a datetime to each data point uploaded to our flask IoT server.