Hitting API Examples with MicroPython

Table of Contents#

1. Fundamental Concepts
2. Usage Methods
3. Common Practices
4. Best Practices
5. Conclusion
6. References

1. Fundamental Concepts#

What is an API?#

An API, or Application Programming Interface, is a set of rules and protocols that allows different software applications to communicate with each other. APIs expose a set of functions or endpoints that other applications can call to perform specific tasks, such as retrieving data, sending data, or triggering an action.

MicroPython and APIs#

MicroPython can interact with APIs over the network, typically using HTTP or HTTPS protocols. MicroPython has libraries like urequests which is a lightweight version of the popular requests library in Python. This library allows MicroPython to send HTTP requests to API endpoints and receive responses.

HTTP Methods#

• GET: Used to retrieve data from an API endpoint. For example, getting the current weather data from a weather API.
• POST: Used to send data to an API endpoint, often to create a new resource. For example, submitting a form to a web-based API.
• PUT: Used to update an existing resource at an API endpoint.
• DELETE: Used to delete a resource at an API endpoint.

2. Usage Methods#

Prerequisites#

To hit an API with MicroPython, you need a microcontroller with Wi-Fi capabilities (such as the ESP8266 or ESP32) and the urequests library. You also need to be connected to a Wi-Fi network.

Connecting to Wi-Fi#

import network
 
# Replace with your network credentials
ssid = 'your_SSID'
password = 'your_PASSWORD'
 
# Connect to Wi - Fi
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(ssid, password)
 
# Wait for connection
while not wlan.isconnected():
    pass
 
print('Connected to Wi - Fi')

Making a GET Request#

import urequests
 
# API endpoint URL
url = 'https://jsonplaceholder.typicode.com/todos/1'
 
# Make a GET request
response = urequests.get(url)
 
# Check if the request was successful
if response.status_code == 200:
    # Print the JSON response
    print(response.json())
else:
    print('Request failed with status code:', response.status_code)
 
# Close the response
response.close()

Making a POST Request#

import urequests
import json
 
# API endpoint URL
url = 'https://jsonplaceholder.typicode.com/posts'
 
# Data to send
data = {
    'title': 'foo',
    'body': 'bar',
    'userId': 1
}
 
# Convert data to JSON
json_data = json.dumps(data)
 
# Make a POST request
response = urequests.post(url, headers={'Content-Type': 'application/json'}, data=json_data)
 
# Check if the request was successful
if response.status_code == 201:
    print(response.json())
else:
    print('Request failed with status code:', response.status_code)
 
# Close the response
response.close()

3. Common Practices#

Error Handling#

It's important to handle errors when making API requests. Network issues, invalid URLs, or incorrect API keys can cause requests to fail. You can use try-except blocks to catch exceptions.

import urequests
 
url = 'https://invalid-url.com'
try:
    response = urequests.get(url)
    if response.status_code == 200:
        print(response.json())
    else:
        print('Request failed with status code:', response.status_code)
    response.close()
except Exception as e:
    print('An error occurred:', e)

Parsing JSON Responses#

Most APIs return data in JSON format. MicroPython has a ujson library to parse JSON data.

import urequests
import ujson
 
url = 'https://jsonplaceholder.typicode.com/todos/1'
response = urequests.get(url)
if response.status_code == 200:
    data = ujson.loads(response.text)
    print(data['title'])
response.close()

4. Best Practices#

Rate Limiting#

Many APIs have rate limits, which restrict the number of requests you can make within a certain time period. To avoid hitting these limits, you can implement a delay between requests.

import urequests
import time
 
url = 'https://example-api.com'
for i in range(5):
    response = urequests.get(url)
    if response.status_code == 200:
        print(response.json())
    response.close()
    time.sleep(1)  # Wait for 1 second between requests

Security#

When making API requests, especially over HTTPS, make sure to use secure connections. If an API requires authentication, use API keys or tokens securely. Do not hard-code API keys in your code; instead, store them in a secure location.

5. Conclusion#

Hitting APIs with MicroPython is a powerful way to connect microcontrollers to the internet and access a wide range of data and services. By understanding the fundamental concepts, using the right usage methods, following common practices, and implementing best practices, you can effectively interact with APIs in your MicroPython projects. Whether you are building a weather station, a home automation system, or a remote monitoring device, API integration can enhance the functionality of your projects.

6. References#

• MicroPython official documentation: https://docs.micropython.org/
• urequests library: https://github.com/micropython/micropython-lib/tree/master/urequests
• JSONPlaceholder API: https://jsonplaceholder.typicode.com/