ESP32 HTTP Client Without the Headache: Consuming REST APIs with Zero Memory Allocation

Consuming REST APIs on ESP32 Without Heap Crashes: Meet ESP32-HTTP-Client If you have ever developed IoT projects on the ESP32 that interact with REST APIs (pushing sensor telemetry, querying cloud services, or integrating with Firebase and AWS), you have likely run into these classic bottlenecks: - Heap Fragmentation & Out-of-Memory Crashes: The standard HTTPClient +ArduinoJson workflow loads the entire HTTP payload into RAM as aString before parsing. With medium to large JSON payloads, this often leads to heap fragmentation and unpredictable crashes. - High Latency on Consecutive Requests: The default Arduino HTTPClient tears down and re-establishes TCP/TLS handshakes on every request, adding hundreds of milliseconds of overhead to every telemetry cycle. - Excessive Boilerplate: Writing 15 to 20 lines of repetitive code just to initialize clients, handle buffers, verify error status codes, and extract individual JSON nodes. To solve these pain points with a clean, modern architecture, ESP32-HTTP-Client was created. What is ESP32-HTTP-Client? ESP32-HTTP-Client is a lightweight, fluent, and object-oriented HTTP/REST client for ESP32, designed specifically for memory-constrained embedded systems. Rather than "buffering the entire response into RAM and then parsing", it leverages Direct Memory Binding and Stream-Based Parsing: JSON values are parsed directly from the incoming network stream and injected straight into your C++ variables or struct s, never buffering the full payload in RAM. // One line. Zero intermediate string buffers. Direct memory binding. client.get("/sensor").getBody("temperature", &myFloatVariable); Performance Benchmark: ESP32-HTTP-Client vs Standard Approach In benchmark tests running 100 consecutive HTTP GET requests with JSON payloads (using the public JSONPlaceholder /users endpoint), the results highlight significant resource savings: | Metric / Feature | HTTPClient + ArduinoJson (Standard) | ESP32-HTTP-Client | Comparison | |---|---|---|---| | Heap Allocated per Request | ~58.2 KB | ~0.0 KB (15 bytes) | ~99.9% less RAM per request | | Average System RAM Used | ~34.2% | ~24.3% | ~29% less overall RAM consumed | | Absolute Min Free Heap | 114.3 KB | 128.6 KB | Much safer for complex IoT apps | | Average Execution Time | ~750 ms | ~59 ms | ~12x faster (Native Keep-Alive) | | Lines of Code | ~15-20 lines | 1 fluent chain | Clean, readable, maintainable | | JSON Parsing Model | Requires DynamicJsonDocument | Streaming directly to variables | Zero buffer allocation | Why is it so much faster? ESP32-HTTP-Client maintains the underlying TCP/TLS connection open across calls (HTTP Keep-Alive) and decodesTransfer-Encoding: chunked on the fly. This eliminates the heavy overhead of re-running TLS cryptographic handshakes on every reading. Quick Start: Your First Request in 2 Minutes Installation - PlatformIO (add to your platformio.ini ): lib_deps = PedroFnseca/ESP32-HTTP-Client@^1.4.0 - Arduino IDE: Navigate to Sketch → Include Library → Manage Libraries..., search for ESP32-HTTP-Client , and click Install. Basic Example: GET Request with Direct Binding #include #include #include "ESP32HTTPClient.h" const char* ssid = "YOUR_SSID"; const char* password = "YOUR_PASSWORD"; // Initialize client with base URL ESP32HTTPClient client("https://jsonplaceholder.typicode.com"); void setup() { Serial.begin(115200); WiFi.begin(ssid, password); while (WiFi.status() != WL_CONNECTED) delay(100); int userId = 0; char title[64] = {0}; bool completed = false; // Expected JSON: { "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false } client.get("/todos/1") .getBody("userId", &userId) .getBody("title", title, sizeof(title)) .getBody("completed", &completed); Serial.printf("User ID: %d | Title: %s | Completed: %s\n", userId, title, completed ? "true" : "false"); } void loop() {} Advanced Features for Production IoT ESP32-HTTP-Client provides a complete toolset for real-world IoT applications: 1. Bidirectional Struct JSON Mapping Map entire C++ structures using the REST_JSON_MAP macro. You can send and receive typed objects without manual serialization logic: // 1. Declare struct with mapped fields struct DeviceTelemetry { int deviceId = 101; float temperature = 26.4; float humidity = 58.0; bool statusOk = true; REST_JSON_MAP( REST_FIELD(deviceId), REST_FIELD(temperature), REST_FIELD(humidity), REST_FIELD(statusOk) ) }; // 2. Send struct directly in POST body (zero-copy serialization) DeviceTelemetry telemetry; client.post("/api/telemetry").body(telemetry); // 3. Populate struct directly from response DeviceTelemetry serverConfig; client.get("/api/config").getBody(&serverConfig); 2. Built-in Authentication Helpers (Bearer, Basic, API Key) Set persistent authentication headers for the lifecycle of your client: // JWT / Bearer Token client.bearer("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ..."); // HTTP Basic Auth (Base64 automatically computed) client.basic("admin", "superSecretPassword"); // Custom API Key Header client.apiKey("X-API-KEY", "your-access-key"); 3. Nested Field Extraction & Array Indexing Extract deeply nested fields or specific array elements without loading the entire JSON tree into memory: char cityName[32]; int secondSensorVal; // Dot notation navigation: { "company": { "address": { "city": "San Francisco" } } } client.get("/profile").getBody("company.address.city", cityName, sizeof(cityName)); // Array indexing: [ { "val": 10 }, { "val": 25 } ] client.get("/sensors").getBody("1.val", &secondSensorVal); 4. Network Resilience: Timeouts, Auto-Retries & Callbacks On unreliable IoT networks, configure timeouts, automatic retry policies, and declarative callbacks: client.get("/telemetry") .timeout(3000) // 3-second timeout for this request .retry(2) // Retry up to 2 times on network drops .onSuccess([](int code) { Serial.printf("Request succeeded! HTTP Code: %d\n", code); }) .onError([](int code, const char* msg) { Serial.printf("Request failed (%d): %s\n", code, msg); }) .getBody("status", &statusVar); 5. Efficient Connection & TLS Buffer Management Keep-Alive preserves the socket and TLS buffers (~45 KB) for instant subsequent calls. When preparing for Deep Sleep or long idle intervals, release TLS buffers immediately: // Fast burst of telemetry calls using Keep-Alive client.get("/sync/1").getBody("val", &v1); client.get("/sync/2").getBody("val", &v2); // Free TLS memory before sleep or extended delay client.end(); Why Choose ESP32-HTTP-Client? - Zero Heap Leaks: Eliminates crashes caused by String heap fragmentation and heavy JSON buffers. - Lower Energy Consumption: 12x faster network transactions mean the Wi-Fi radio is powered for less time. - Readable Codebase: Fluent API replaces repetitive boilerplate with concise, expressive statements. - Production-Ready: Includes comprehensive unit tests and full support for all HTTP methods ( GET ,POST ,PUT ,PATCH ,DELETE ). Official Links & Resources - Official Documentation - Full guides, API reference, and tutorials. - GitHub Repository - Source code, issue tracker, and contributions. - Examples Directory - Ready-to-flash sketches for Arduino IDE and PlatformIO. Top comments (0)