ESP32 REST API Server met JSON - Complete Handleiding
WebServerJson Voorbeeld - REST API Server
Overzicht
Dit voorbeeld toont hoe u een REST API server maakt op de ESP32 die JSON-requests en -responses verwerkt, perfect voor moderne webapplicaties en backend van mobiele apps.
Functies
- REST API endpoints met JSON request/response verwerking
- POST request verwerking met JSON data parsing
- GET endpoints voor gegevensopvraging
- Professionele JSON responses met correcte HTTP statuscodes
- Foutafhandeling met passende JSON foutmeldingen
- CORS ondersteuning voor cross-origin requests
Benodigde Hardware
Of u kunt de volgende kits kopen:
| 1 | × | DIYables Sensorkit (30 sensoren/displays) | |
| 1 | × | DIYables Sensorkit (18 sensoren/displays) |
Openbaarmaking: Sommige van de links in deze sectie zijn Amazon-affiliate links. We kunnen een commissie ontvangen voor aankopen die via deze links worden gedaan, zonder extra kosten voor u. We waarderen uw steun.
Bibliotheek Installatie
Volg deze instructies stap voor stap:
- Als u voor het eerst met de ESP32 werkt, raadpleeg dan de tutorial over het instellen van de ESP32 omgeving in de Arduino IDE.
- Verbind de ESP32 via USB-kabel met uw computer.
- Start de Arduino IDE op uw computer.
- Selecteer de juiste ESP32 board (bijvoorbeeld ESP32) en juiste COM-poort.
- Open de Library Manager door te klikken op het Library Manager icoon aan de linkerkant van de Arduino IDE.
- Zoek op Web Server for ESP32 en selecteer mWebSockets van DIYables.
- Klik op de Installeren-knop om de mWebSockets bibliotheek toe te voegen.
Web Server Json Voorbeeld
- In de Arduino IDE, ga naar Bestand Voorbeelden Web Server for ESP32 WebServerJson om de voorbeeldcode te openen
API Endpoints
GET /api/data
Retourneert een succesbericht met timestamp in JSON-formaat.
Response:
{
"status": "success",
"message": "GET request received",
"timestamp": 12345
}
De timestamp geeft milliseconden aan sinds het opstarten van de ESP32 (via de functie millis()).
POST /api/data
Accepteert JSON data en retourneert de ontvangen key-waarde.
Request:
{
"key": "your_value"
}
Response:
{
"status": "success",
"message": "Data received",
"received_key": "your_value"
}
Installatie-instructies
1. Netwerkconfiguratie
Pas de WiFi-gegevens aan in het bestand WebServerJson.ino:
const char WIFI_SSID[] = "YOUR_WIFI_SSID";
const char WIFI_PASSWORD[] = "YOUR_WIFI_PASSWORD";
2. Upload Code en Monitor Output
- Verbind uw ESP32 met de computer
- Selecteer het juiste board en poort in de Arduino IDE
- Upload de sketch WebServerJson.ino
- Open de Seriële Monitor (9600 baud)
- Wacht op de WiFi-verbinding
- Noteer het weergegeven IP-adres
- Als u het IP-adres niet ziet, druk dan op de resetknop van de ESP32
Gebruik
Testen met cURL
Vervang your-esp32-ip door het daadwerkelijke IP-adres dat wordt weergegeven in uw Seriële Monitor.
Test GET Request
curl -X GET http://your-esp32-ip/api/data
Verwachte Output:
Command Prompt
C:\Users\youruser>curl -X GET http://your-esp32-ip/api/data
{
"status": "success",
"message": "GET request received",
"timestamp": 12345
}
De timestamp geeft milliseconden sinds het opstarten van de ESP32 weer.
Test POST Request met JSON Data
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"test_value\"}"
Verwachte Output:
Command Prompt
C:\Users\youruser>curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"test_value\"}"
{
"status": "success",
"message": "Data received",
"received_key": "test_value"
}
Test POST Request met andere Data
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"hello_world\"}"
Verwachte Output:
Command Prompt
C:\Users\youruser>curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"hello_world\"}"
{
"status": "success",
"message": "Data received",
"received_key": "hello_world"
}
Test Ongeldige JSON (Foutresponse)
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{invalid json}"
Verwachte Output:
Command Prompt
C:\Users\youruser>curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{invalid json}"
{
"status": "error",
"message": "Invalid JSON"
}
Test Ontbrekende JSON Body (Foutresponse)
curl -X POST http://your-esp32-ip/api/data
Verwachte Output:
Command Prompt
C:\Users\youruser>curl -X POST http://your-esp32-ip/api/data
{
"status": "error",
"message": "No JSON data received"
}
Test Niet-ondersteunde Methode (Foutresponse)
curl -X PUT http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"test\"}"
Verwachte Output:
Command Prompt
C:\Users\youruser>curl -X PUT http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"test\"}"
{
"status": "error",
"message": "Method not allowed"
}
Test Niet-bestaande Endpoint (404 Fout)
curl -X GET http://your-esp32-ip/api/nonexistent
Verwachte Output:
Command Prompt
C:\Users\youruser>curl -X GET http://your-esp32-ip/api/nonexistent
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>404 Not Found</title>
</head>
<body>
<h1>404 - Page Not Found</h1>
<p>Method: GET</p>
<p>Sorry, we couldn't find that page!</p>
<a href="/">Return to Home</a>
</body>
</html>
Testen met Postman
Test GET Request
- Maak een nieuwe GET-aanvraag aan
- Stel de URL in op http://your-esp32-ip/api/data
- Verstuur de aanvraag
- Controleer of de response status, message en timestamp bevat
Test POST Request
- Maak een nieuwe POST-aanvraag aan
- Stel de URL in op http://your-esp32-ip/api/data
- Voeg header toe: Content-Type: application/json
- Voeg JSON-body toe: {"key": "test_value"}
- Verstuur de aanvraag
- Controleer of de response de ontvangen key-waarde toont
Testen van Foutresponses
Test de foutafhandeling door ongeldige requests te sturen zoals in de voorbeeldcode:
Ontbrekende JSON Data
curl -X POST http://your-esp32-ip/api/data
Verwacht: {"status": "error","message": "No JSON data received"}
Ongeldige JSON Syntax
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{invalid json}"
Verwacht: {"status": "error","message": "Invalid JSON"}
Ontbrekend Key-veld
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"other_field\": \"value\"}"
Verwacht: De key krijgt standaardwaarde "none" volgens de voorbeeldcode: doc["key"] | "none"
Niet-ondersteunde HTTP Methode
curl -X DELETE http://your-esp32-ip/api/data
Verwacht: {"status": "error","message": "Method not allowed"}
Code Uitleg
Route Configuratie
// Configureer API routes
server.addRoute("/api/data", handleApiData);
Handler Functiesignatuur
Alle handlerfuncties volgen deze handtekening:
void handleApiData(WiFiClient& client, const String& method, const String& request, const QueryParams& params, const String& jsonData) {
// Handler implementatie
}
Methode Detectie en JSON Verwerking
void handleApiData(WiFiClient& client, const String& method, const String& request, const QueryParams& params, const String& jsonData) {
Serial.print("[API] ");
Serial.print(method);
Serial.print(" request received");
if (method == "POST") {
if (jsonData.length() == 0) {
Serial.println("Error: No JSON data received");
client.println("HTTP/1.1 400 Bad Request");
client.println("Content-Type: application/json");
client.println("Connection: close");
client.println();
client.print("{\"status\": \"error\",\"message\": \"No JSON data received\"}");
return;
}
StaticJsonDocument<200> doc;
DeserializationError error = deserializeJson(doc, jsonData);
if (!error) {
const char* key = doc["key"] | "none";
String response = JSON_RESPONSE;
response.replace("%KEY%", key);
server.sendResponse(client, response.c_str(), "application/json");
} else {
client.println("HTTP/1.1 400 Bad Request");
client.println("Content-Type: application/json");
client.println("Connection: close");
client.println();
client.print("{\"status\": \"error\",\"message\": \"Invalid JSON\"}");
}
} else if (method == "GET") {
String response = JSON_GET_RESPONSE;
response.replace("%TIMESTAMP%", String(millis()));
server.sendResponse(client, response.c_str(), "application/json");
} else {
client.println("HTTP/1.1 405 Method Not Allowed");
client.println("Content-Type: application/json");
client.println("Connection: close");
client.println();
client.print("{\"status\":\"error\",\"message\":\"Method not allowed\"}");
}
}
Integratievoorbeelden
JavaScript Frontend
// LED bedienen
async function controlLED(action) {
try {
const response = await fetch('http://your-esp32-ip/api/led', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({ action: action })
});
const result = await response.json();
console.log('LED control result:', result);
} catch (error) {
console.error('Error:', error);
}
}
// Sensor data ophalen
async function getSensorData() {
try {
const response = await fetch('http://your-esp32-ip/api/sensor');
const data = await response.json();
console.log('Sensor data:', data);
} catch (error) {
console.error('Error:', error);
}
}
Python Client
import requests
import json
LED bedienen
def control_led(action):
url = "http://your-esp32-ip/api/led"
data = {"action": action}
response = requests.post(url, json=data)
return response.json()
Status ophalen
def get_status():
url = "http://your-esp32-ip/api/status"
response = requests.get(url)
return response.json()
Gebruik
result = control_led("on")
print(result)
status = get_status()
print(status)
Foutafhandeling
HTTP Statuscodes
- 200: Succes
- 400: Bad Request (ongeldige JSON, ontbrekende parameters)
- 404: Endpoint niet gevonden
- 405: Methode niet toegestaan
- 500: Interne serverfout
Foutresponse Formaat
Gebaseerd op de voorbeeldcode worden specifieke foutmeldingen als volgt teruggegeven:
Fout bij Ontbrekende JSON Data
{
"status": "error",
"message": "No JSON data received"
}
Teruggegeven wanneer: een POST request wordt verzonden zonder JSON body
Fout bij Ongeldige JSON Syntax
{
"status": "error",
"message": "Invalid JSON"
}
Teruggegeven wanneer: JSON data niet geparsed kan worden (syntaxfouten)
Fout bij Methode Niet Toegestaan
{
"status": "error",
"message": "Method not allowed"
}
Teruggegeven wanneer: gebruik van niet-ondersteunde HTTP methoden (PUT, DELETE, PATCH, etc.)
404 Niet Gevonden Fout
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>404 Not Found</title>
</head>
<body>
<h1>404 - Page Not Found</h1>
<p>Method: [HTTP_METHOD]</p>
<p>Sorry, we couldn't find that page!</p>
<a href="/">Return to Home</a>
</body>
</html>
Teruggegeven wanneer: niet-bestaande endpoints worden opgevraagd
Aanpassingen
Nieuwe Handler Functies Toevoegen
// Maak extra handler aan voor een nieuw endpoint
void handleApiStatus(WiFiClient& client, const String& method, const String& request, const QueryParams& params, const String& jsonData) {
if (method == "GET") {
String json = "{\"status\":\"online\",\"uptime\":" + String(millis() / 1000) + "}";
server.sendResponse(client, json.c_str(), "application/json");
} else {
client.println("HTTP/1.1 405 Method Not Allowed");
client.println("Content-Type: application/json");
client.println("Connection: close");
client.println();
client.print("{\"status\":\"error\",\"message\":\"Method not allowed\"}");
}
}
// Registreer de nieuwe route in setup()
server.addRoute("/api/status", handleApiStatus);
Template-gebaseerde JSON Responses
Het voorbeeld maakt gebruik van templatestrings voor consistente JSON-formattering:
const char JSON_RESPONSE[] PROGMEM = R"rawliteral(
{
"status": "success",
"message": "Data received",
"received_key": "%KEY%"
}
)rawliteral";
// Gebruik in handler
String response = JSON_RESPONSE;
response.replace("%KEY%", extractedValue);
server.sendResponse(client, response.c_str(), "application/json");
Probleemoplossing
Veelvoorkomende Problemen
Verbindingsproblemen
Als u geen verbinding kunt maken met de API endpoints:
- Controleer of uw ESP32 verbonden is met WiFi (via Seriële Monitor)
- Zorg dat client en ESP32 op hetzelfde netwerk zitten
- Controleer of het IP-adres correct is
- Controleer of de ESP32 niet is gereset (anders verandert IP)
JSON Parsing Fouten
Als u "Invalid JSON" meldingen krijgt:
- Zorg dat de header Content-Type op application/json staat
- Controleer of uw JSON-syntax geldig is
- Let op correcte escaping van speciale tekens
- Zorg dat de JSON payload niet groter is dan de limiet (nu 200 bytes)
POST Request Problemen
Als POST requests "No JSON data received" teruggeven:
- Stuur een geldige JSON body mee
- Controleer dat de Content-Length header klopt
- Verifieer dat de HTTP-methode daadwerkelijk POST is
- Test met een eenvoudige JSON zoals {"key": "test"}
Geheugenproblemen
Als de ESP32 niet meer reageert:
- Houd het geheugengebruik in de gaten - StaticJsonDocument gebruikt 200 bytes
- Verklein indien nodig de JSON_RESPONSE template
- Overweeg DynamicJsonDocument voor variabele JSON-grootte
- Controleer op geheugenlekken in eigen handlerfuncties
Prestatie Tips
JSON Verwerking Optimaliseren
// Gebruik passende documentgrootte voor uw data
StaticJsonDocument<200> doc; // Voor kleine JSON-objecten
StaticJsonDocument<1024> doc; // Voor grotere JSON-objecten
// Hergebruik String-objecten om geheugenallocatie te beperken
String response;
response.reserve(256); // Reserveer geheugen vooraf
response = JSON_RESPONSE;
response.replace("%KEY%", value);
Efficiënte Response Verwerking
// Stuur responses direct bij eenvoudige gevallen
client.print(F("{\"status\":\"ok\",\"value\":"));
client.print(sensorValue);
client.print(F("}"));
// Gebruik PROGMEM voor grote statische responses
const char LARGE_RESPONSE[] PROGMEM = R"({
"status": "success",
"data": { ... }
})";
Volgende Stappen
- Verken WebServerQueryStrings.ino voor URL parameter handling
- Probeer WebServerWithWebSocket.ino voor real-time communicatie
- Overweeg integratie met databases of cloud diensten