DIYables ESP32 Web Server Json Example
WebServerJson Example - REST API Server
Overview
This example demonstrates how to create a REST API server on ESP32 that handles JSON requests and responses, perfect for modern web applications and mobile app backends.
Features
- REST API endpoints with JSON request/response handling
- POST request processing with JSON data parsing
- GET endpoints for data retrieval
- Professional JSON responses with proper HTTP status codes
- Error handling with appropriate JSON error messages
- CORS support for cross-origin requests
Hardware Used In This Tutorial
Or you can buy the following kits:
| 1 | × | DIYables ESP32 Starter Kit (ESP32 included) | |
| 1 | × | DIYables Sensor Kit (30 sensors/displays) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Disclosure: Some of the links in this section are Amazon affiliate links, meaning we may earn a commission at no additional cost to you if you make a purchase through them. Additionally, some links direct you to products from our own brand, DIYables .
Library Installation
Follow these instructions step by step:
- If this is your first time using the ESP32, refer to the tutorial on setting up the environment for ESP32 in the Arduino IDE.
- Connect the ESP32 board to your computer using a USB cable.
- Launch the Arduino IDE on your computer.
- Select the appropriate ESP32 board (e.g., ESP32) and COM port.
- Open the Library Manager by clicking on the Library Manager icon on the left side of the Arduino IDE.
- Search for Web Server for ESP32 and locate the mWebSockets by DIYables.
- Click on the Install button to add the mWebSockets library.
Web Server Json Example
- On Arduino IDE, Go to File Examples Web Server for ESP32 WebServerJson example to open the example code
API Endpoints
GET /api/data
Returns a success message with timestamp in JSON format.
Response:
{
"status": "success",
"message": "GET request received",
"timestamp": 12345
}
The timestamp value represents milliseconds since the ESP32 started (from millis() function).
POST /api/data
Accepts JSON data and returns the received key value.
Request:
{
"key": "your_value"
}
Response:
{
"status": "success",
"message": "Data received",
"received_key": "your_value"
}
Setup Instructions
1. Network Configuration
Edit the WiFi credentials in the WebServerJson.ino file:
const char WIFI_SSID[] = "YOUR_WIFI_SSID";
const char WIFI_PASSWORD[] = "YOUR_WIFI_PASSWORD";
2. Upload Code and Monitor Output
- Connect your ESP32 to your computer
- Select the correct board and port in Arduino IDE
- Upload the WebServerJson.ino sketch
- Open Serial Monitor (9600 baud)
- Wait for WiFi connection
- Note the IP address displayed
- If you do not see IP address in Serial monitor, press the reset button on the ESP32 board
Usage
Testing with cURL
Replace your-esp32-ip with the actual IP address shown in your Serial Monitor.
Test GET Request
curl -X GET http://your-esp32-ip/api/data
Expected Output:
Command Prompt
C:\Users\youruser>curl -X GET http://your-esp32-ip/api/data
{
"status": "success",
"message": "GET request received",
"timestamp": 12345
}
The timestamp shows milliseconds since ESP32 startup.
Test POST Request with JSON Data
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"test_value\"}"
Expected 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 with Different Data
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"hello_world\"}"
Expected 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 Invalid JSON (Error Response)
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{invalid json}"
Expected 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 Missing JSON Body (Error Response)
curl -X POST http://your-esp32-ip/api/data
Expected Output:
Command Prompt
C:\Users\youruser>curl -X POST http://your-esp32-ip/api/data
{
"status": "error",
"message": "No JSON data received"
}
Test Unsupported Method (Error Response)
curl -X PUT http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"key\": \"test\"}"
Expected 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 Non-existent Endpoint (404 Error)
curl -X GET http://your-esp32-ip/api/nonexistent
Expected 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>
Testing with Postman
Test GET Request
- Create a new GET request
- Set URL to http://your-esp32-ip/api/data
- Send request
- Verify response contains status, message, and timestamp
Test POST Request
- Create a new POST request
- Set URL to http://your-esp32-ip/api/data
- Add header: Content-Type: application/json
- Add JSON body: {"key": "test_value"}
- Send request
- Verify response shows the received key value
Testing Error Responses
Test the error handling by sending invalid requests as shown in the example code:
Missing JSON Data
curl -X POST http://your-esp32-ip/api/data
Expected: {"status": "error","message": "No JSON data received"}
Invalid JSON Format
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{invalid json}"
Expected: {"status": "error","message": "Invalid JSON"}
Missing Key Field
curl -X POST http://your-esp32-ip/api/data -H "Content-Type: application/json" -d "{\"other_field\": \"value\"}"
Expected: The key will default to "none" as per the example code: doc["key"] | "none"
Unsupported HTTP Method
curl -X DELETE http://your-esp32-ip/api/data
Expected: {"status": "error","message": "Method not allowed"}
Code Explanation
Route Configuration
// Configure API routes
server.addRoute("/api/data", handleApiData);
Handler Function Signature
All handler functions must follow this signature:
void handleApiData(WiFiClient& client, const String& method, const String& request, const QueryParams& params, const String& jsonData) {
// Handler implementation
}
Method Detection and JSON Processing
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\"}");
}
}
Integration Examples
JavaScript Frontend
// Control LED
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);
}
}
// Get sensor data
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
Control LED
def control_led(action):
url = "http://your-esp32-ip/api/led"
data = {"action": action}
response = requests.post(url, json=data)
return response.json()
Get status
def get_status():
url = "http://your-esp32-ip/api/status"
response = requests.get(url)
return response.json()
Usage
result = control_led("on")
print(result)
status = get_status()
print(status)
Error Handling
HTTP Status Codes
- 200: Success
- 400: Bad Request (invalid JSON, missing parameters)
- 404: Endpoint not found
- 405: Method not allowed
- 500: Internal server error
Error Response Format
Based on the actual example code, different errors return specific messages:
Missing JSON Data Error
{
"status": "error",
"message": "No JSON data received"
}
Returned when: POST request is sent without JSON body
Invalid JSON Format Error
{
"status": "error",
"message": "Invalid JSON"
}
Returned when: JSON data cannot be parsed (syntax errors)
Method Not Allowed Error
{
"status": "error",
"message": "Method not allowed"
}
Returned when: Using unsupported HTTP methods (PUT, DELETE, PATCH, etc.)
404 Not Found Error
<!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>
Returned when: Accessing non-existent endpoints
Customization
Adding New Handler Functions
// Create additional handler for a new 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\"}");
}
}
// Register the new route in setup()
server.addRoute("/api/status", handleApiStatus);
Template-Based JSON Responses
The example uses template strings for consistent JSON formatting:
const char JSON_RESPONSE[] PROGMEM = R"rawliteral(
{
"status": "success",
"message": "Data received",
"received_key": "%KEY%"
}
)rawliteral";
// Usage in handler
String response = JSON_RESPONSE;
response.replace("%KEY%", extractedValue);
server.sendResponse(client, response.c_str(), "application/json");
Troubleshooting
Common Issues
Connection Issues
If you can't connect to the API endpoints:
- Verify your ESP32 is connected to WiFi (check Serial Monitor)
- Ensure your client and ESP32 are on the same network
- Check that the IP address is correct
- Verify the ESP32 hasn't reset (which would change the IP)
JSON Parsing Errors
If you get "Invalid JSON" responses:
- Ensure Content-Type header is set to application/json
- Verify your JSON syntax is valid
- Check that special characters are properly escaped
- Make sure the JSON payload isn't too large (current limit: 200 bytes)
POST Request Issues
If POST requests return "No JSON data received":
- Verify you're sending a JSON body with the request
- Check that Content-Length header is set correctly
- Ensure the HTTP method is actually POST
- Test with a simple JSON like {"key": "test"}
Memory Issues
If the ESP32 becomes unresponsive:
- Monitor memory usage - the StaticJsonDocument uses 200 bytes
- Reduce JSON_RESPONSE template size if needed
- Consider using DynamicJsonDocument for variable-sized data
- Check for memory leaks in custom handler functions
Performance Tips
Optimize JSON Processing
// Use appropriate document size for your data
StaticJsonDocument<200> doc; // For small JSON objects
StaticJsonDocument<1024> doc; // For larger JSON objects
// Reuse string objects to reduce memory allocation
String response;
response.reserve(256); // Pre-allocate space
response = JSON_RESPONSE;
response.replace("%KEY%", value);
Efficient Response Handling
// Send responses directly for simple cases
client.print(F("{\"status\":\"ok\",\"value\":"));
client.print(sensorValue);
client.print(F("}"));
// Use PROGMEM for large static responses
const char LARGE_RESPONSE[] PROGMEM = R"({
"status": "success",
"data": { ... }
})";
Next Steps
- Explore WebServerQueryStrings.ino for URL parameter handling
- Try WebServerWithWebSocket.ino for real-time communication
- Consider integrating with databases or cloud services