ESP32 REST-API abfragen: JSON mit ArduinoJson parsen & Live-Daten aufs OLED bringen

Was bei einer API-Abfrage eigentlich passiert

Eine REST-API ist im Kern nichts anderes als eine Webseite, die statt HTML strukturierte Daten zurückgibt. Du schickst eine ganz normale HTTP-Anfrage an eine URL, der Server antwortet mit einem Statuscode und einem Textkörper. Bei einer API ist dieser Textkörper JSON – ein Format aus geschweiften Klammern, Schlüsseln und Werten.

GET /data/2.5/weather?q=Berlin&units=metric HTTP/1.1
Host: api.example.com

--- Antwort ---
HTTP/1.1 200 OK
Content-Type: application/json

{
  "main": { "temp": 18.4, "humidity": 71, "pressure": 1014 },
  "weather": [ { "main": "Clouds", "description": "bedeckt" } ],
  "name": "Berlin"
}

Für den ESP32 zerfällt die Aufgabe damit in drei Teile, die du getrennt voneinander lösen und testen kannst:

Das brauchst du

Software: Arduino IDE mit ESP32-Boardpaket und die Bibliothek ArduinoJson (Bibliotheksverwalter, Autor Benoit Blanchon) in Version 7 oder neuer.

1Verkabelung

2Die erste Abfrage: rohe Antwort auf dem Serial Monitor

Bevor irgendetwas geparst wird, willst du sehen, was überhaupt ankommt. Dieser Sketch verbindet sich mit dem WLAN, holt eine Testantwort und gibt sie unverändert aus:

#include <WiFi.h>
#include <HTTPClient.h>

const char* WLAN_SSID = "DeinNetz";
const char* WLAN_PASS = "DeinPasswort";

// Testendpunkt ohne Schluessel: liefert die aktuelle Zeit als JSON
const char* API_URL = "http://worldtimeapi.org/api/timezone/Europe/Berlin";

void wlanVerbinden() {
  WiFi.mode(WIFI_STA);
  WiFi.begin(WLAN_SSID, WLAN_PASS);

  Serial.print(F("Verbinde"));
  uint8_t versuche = 0;
  while (WiFi.status() != WL_CONNECTED && versuche < 40) {
    delay(250);
    Serial.print('.');
    versuche++;
  }
  Serial.println();

  if (WiFi.status() == WL_CONNECTED) {
    Serial.print(F("IP: "));
    Serial.println(WiFi.localIP());
    Serial.print(F("RSSI: "));
    Serial.println(WiFi.RSSI());
  } else {
    Serial.println(F("WLAN fehlgeschlagen"));
  }
}

void setup() {
  Serial.begin(115200);
  delay(300);
  wlanVerbinden();

  if (WiFi.status() != WL_CONNECTED) return;

  HTTPClient http;
  http.begin(API_URL);
  http.setTimeout(8000);                 // nicht ewig warten
  http.addHeader("User-Agent", "ESP32-MAKEROO");

  int code = http.GET();
  Serial.print(F("HTTP-Code: "));
  Serial.println(code);

  if (code > 0) {
    String antwort = http.getString();
    Serial.print(F("Laenge: "));
    Serial.println(antwort.length());
    Serial.println(F("--- Rohantwort ---"));
    Serial.println(antwort);
  } else {
    // Negative Codes sind Client-Fehler, keine Serverantworten
    Serial.print(F("Fehler: "));
    Serial.println(http.errorToString(code));
  }

  http.end();                            // Verbindung sauber schliessen
}

void loop() {
}

3JSON zerlegen mit ArduinoJson

Jetzt der eigentliche Trick. Man könnte mit indexOf() und substring() im Antworttext herumsuchen – das funktioniert genau so lange, bis der Server ein Feld umsortiert. ArduinoJson baut stattdessen einen echten Objektbaum auf, aus dem du Werte über ihren Pfad holst:

#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

struct Wetter {
  float   temperatur   = NAN;
  float   gefuehlt     = NAN;
  uint8_t feuchte      = 0;
  uint16_t druck       = 0;
  String  beschreibung = "";
  bool    gueltig      = false;
};

Wetter aktuell;

bool wetterHolen(const String& url) {
  if (WiFi.status() != WL_CONNECTED) return false;

  HTTPClient http;
  http.begin(url);
  http.setTimeout(8000);

  int code = http.GET();
  if (code != HTTP_CODE_OK) {
    Serial.print(F("HTTP-Fehler: "));
    Serial.println(code);
    http.end();
    return false;
  }

  // Ab ArduinoJson 7: JsonDocument waechst dynamisch mit
  JsonDocument doc;

  // Direkt aus dem Stream parsen spart den kompletten String im RAM
  DeserializationError fehler = deserializeJson(doc, http.getStream());
  http.end();

  if (fehler) {
    Serial.print(F("JSON-Fehler: "));
    Serial.println(fehler.c_str());
    return false;
  }

  // Pfade wie im JSON-Baum. Fehlt ein Feld, kommt der Default zurueck.
  aktuell.temperatur   = doc["main"]["temp"]      | NAN;
  aktuell.gefuehlt     = doc["main"]["feels_like"]| NAN;
  aktuell.feuchte      = doc["main"]["humidity"]  | 0;
  aktuell.druck        = doc["main"]["pressure"]  | 0;
  aktuell.beschreibung = doc["weather"][0]["description"] | "unbekannt";
  aktuell.gueltig      = !isnan(aktuell.temperatur);

  return aktuell.gueltig;
}

void wetterAusgeben() {
  if (!aktuell.gueltig) {
    Serial.println(F("Keine gueltigen Daten"));
    return;
  }
  Serial.print(aktuell.temperatur, 1);
  Serial.print(F(" C, "));
  Serial.print(aktuell.feuchte);
  Serial.print(F(" %, "));
  Serial.print(aktuell.druck);
  Serial.print(F(" hPa, "));
  Serial.println(aktuell.beschreibung);
}

Der Pipe-Operator ist dein Sicherheitsnetz

Das | NAN hinter jedem Zugriff ist kein Zufall. Es liefert einen Ersatzwert, falls das Feld fehlt oder den falschen Typ hat. Ohne diesen Default bekommst du bei einer unerwarteten Antwort eine stille Null – und wunderst dich, warum dein Thermostat plötzlich bei 0 °C heizt.

// Nur die Felder behalten, die wirklich gebraucht werden
JsonDocument filter;
filter["main"]["temp"]     = true;
filter["main"]["humidity"] = true;
filter["weather"][0]["description"] = true;

JsonDocument doc;
DeserializationError fehler = deserializeJson(
    doc, http.getStream(), DeserializationOption::Filter(filter));

// Arrays durchlaufen, wenn die API eine Liste liefert
JsonArray liste = doc["list"].as<JsonArray>();
for (JsonObject eintrag : liste) {
  const char* zeit = eintrag["dt_txt"] | "";
  float t          = eintrag["main"]["temp"] | NAN;

  Serial.print(zeit);
  Serial.print(F(" -> "));
  Serial.println(t, 1);
}

// Verbrauchten Speicher pruefen - wichtig beim Dimensionieren
Serial.print(F("JSON belegt: "));
Serial.print(doc.memoryUsage());
Serial.println(F(" Byte"));

4HTTPS: die Hürde, an der die meisten hängenbleiben

Fast jede ernstzunehmende API läuft heute über https://. Der ESP32 kann das – aber er will wissen, wem er vertrauen soll. Es gibt drei Wege, und du solltest wissen, welchen du gerade gehst:

#include <WiFiClientSecure.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

// Root-Zertifikat der Zertifizierungsstelle, PEM-Format.
// Im Browser: Schloss-Symbol -> Zertifikat -> oberste Ebene exportieren.
static const char ROOT_CA[] PROGMEM = R"CERT(
-----BEGIN CERTIFICATE-----
... hier das Root-Zertifikat einfuegen ...
-----END CERTIFICATE-----
)CERT";

bool apiAbfragenSicher(const String& url, JsonDocument& ziel) {
  WiFiClientSecure client;

  // Variante A - schnell und unsicher, nur zum Testen:
  // client.setInsecure();

  // Variante B - so gehoert es sich:
  client.setCACert(ROOT_CA);
  client.setTimeout(10);                 // Sekunden bei WiFiClientSecure

  HTTPClient http;
  if (!http.begin(client, url)) {
    Serial.println(F("begin() fehlgeschlagen"));
    return false;
  }

  http.addHeader("Accept", "application/json");
  // Viele APIs erwarten den Schluessel im Header statt in der URL:
  // http.addHeader("Authorization", "Bearer DEIN_TOKEN");

  int code = http.GET();

  if (code == 429) {
    Serial.println(F("Rate Limit - Abfrageintervall erhoehen"));
    http.end();
    return false;
  }
  if (code != HTTP_CODE_OK) {
    Serial.print(F("HTTP "));
    Serial.println(code);
    http.end();
    return false;
  }

  DeserializationError fehler = deserializeJson(ziel, http.getStream());
  http.end();

  if (fehler) {
    Serial.print(F("JSON: "));
    Serial.println(fehler.c_str());
    return false;
  }
  return true;
}

5Live-Anzeige auf dem OLED

Zahlen im Serial Monitor sind schön zum Debuggen, aber niemand stellt einen Laptop neben den Kaffeevollautomaten. Auf das SSD1306 passen Temperatur groß, Details klein und eine Statuszeile:

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Adafruit_SSD1306 display(128, 64, &Wire, -1);

void displayStarten() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    Serial.println(F("OLED nicht gefunden"));
    while (true) { delay(1000); }
  }
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.display();
}

void zeigeStatus(const char* text) {
  display.clearDisplay();
  display.setTextSize(1);
  display.setCursor(0, 28);
  display.print(text);
  display.display();
}

void zeigeWetter(const Wetter& w, uint32_t alterSekunden) {
  display.clearDisplay();

  // Kopfzeile mit Ort
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.print(F("Berlin"));

  // WLAN-Balken rechts oben aus dem RSSI
  int8_t rssi = WiFi.RSSI();
  uint8_t balken = 0;
  if      (rssi > -60) balken = 4;
  else if (rssi > -70) balken = 3;
  else if (rssi > -80) balken = 2;
  else if (rssi <= -80) balken = 1;

  for (uint8_t i = 0; i < balken; i++) {
    display.fillRect(110 + i * 4, 8 - (i + 1) * 2, 3, (i + 1) * 2, SSD1306_WHITE);
  }

  // Grosse Temperatur
  display.setTextSize(3);
  display.setCursor(0, 14);
  if (w.gueltig) {
    display.print(w.temperatur, 1);
  } else {
    display.print(F("--.-"));
  }
  display.setTextSize(1);
  display.print(F(" C"));

  // Detailzeile
  display.setTextSize(1);
  display.setCursor(0, 42);
  display.print(w.feuchte);
  display.print(F("%  "));
  display.print(w.druck);
  display.print(F(" hPa"));

  // Beschreibung, auf Displaybreite gekuerzt
  display.setCursor(0, 52);
  String kurz = w.beschreibung;
  if (kurz.length() > 14) kurz = kurz.substring(0, 14);
  display.print(kurz);

  // Alter der Daten rechts unten - verraet stille Ausfaelle
  display.setCursor(92, 52);
  display.print(alterSekunden / 60);
  display.print(F("m"));

  display.display();
}

6Robust abfragen: nicht blockieren, sauber wiederholen

Ein delay(600000) in der loop() ist bequem und falsch: Zehn Minuten lang reagiert dein Gerät auf nichts mehr. Diese Schleife fragt regelmäßig ab, wiederholt bei Fehlern mit wachsendem Abstand und bleibt zwischendurch bedienbar:

const uint32_t INTERVALL_MS      = 10UL * 60UL * 1000UL;   // 10 Minuten
const uint32_t RETRY_BASIS_MS    = 15UL * 1000UL;          // 15 s
const uint8_t  RETRY_MAX         = 5;

uint32_t letzteAbfrage   = 0;
uint32_t naechsteAbfrage = 0;
uint8_t  fehlversuche    = 0;
Wetter   aktuell;

void setup() {
  Serial.begin(115200);
  Wire.begin(21, 22);
  displayStarten();
  zeigeStatus("Verbinde WLAN...");

  WiFi.mode(WIFI_STA);
  WiFi.setAutoReconnect(true);        // ESP32 haelt die Verbindung selbst
  WiFi.begin(WLAN_SSID, WLAN_PASS);

  naechsteAbfrage = 0;                // sofort beim Start abfragen
}

void loop() {
  uint32_t jetzt = millis();

  // WLAN weg? Nur melden, der Autoreconnect erledigt den Rest
  if (WiFi.status() != WL_CONNECTED) {
    static uint32_t letzteMeldung = 0;
    if (jetzt - letzteMeldung > 5000) {
      letzteMeldung = jetzt;
      Serial.println(F("warte auf WLAN"));
    }
  }

  if ((int32_t)(jetzt - naechsteAbfrage) >= 0 &&
      WiFi.status() == WL_CONNECTED) {

    bool ok = wetterHolen(API_URL);

    if (ok) {
      letzteAbfrage   = jetzt;
      fehlversuche    = 0;
      naechsteAbfrage = jetzt + INTERVALL_MS;
      Serial.println(F("Update ok"));
    } else {
      fehlversuche++;

      // Exponentiell zurueckziehen: 15s, 30s, 60s, 120s, 240s
      uint32_t wartezeit = RETRY_BASIS_MS * (1UL << min(fehlversuche, RETRY_MAX));
      naechsteAbfrage = jetzt + wartezeit;

      Serial.print(F("Fehlversuch "));
      Serial.print(fehlversuche);
      Serial.print(F(", naechster Versuch in "));
      Serial.print(wartezeit / 1000);
      Serial.println(F(" s"));
    }
  }

  // Anzeige unabhaengig von der Abfrage aktualisieren
  static uint32_t letztesBild = 0;
  if (jetzt - letztesBild >= 1000) {
    letztesBild = jetzt;
    uint32_t alter = (letzteAbfrage == 0) ? 0 : (jetzt - letzteAbfrage) / 1000;
    zeigeWetter(aktuell, alter);
  }

  // Heap im Blick behalten - Leck zeigt sich hier zuerst
  static uint32_t letzterHeapCheck = 0;
  if (jetzt - letzterHeapCheck >= 60000) {
    letzterHeapCheck = jetzt;
    Serial.print(F("Freier Heap: "));
    Serial.println(ESP.getFreeHeap());
  }
}

Troubleshooting

Praxistipps

• Erst im Browser testen. Ruf die API-URL im Browser auf und schau dir die Antwort an. Was dort nicht funktioniert, wird auf dem ESP32 nicht besser.
• API-Schlüssel nicht in den Sketch tippen. Leg ihn in eine separate secrets.h, die du beim Teilen des Codes weglässt. Wer seinen Schlüssel einmal auf GitHub hatte, macht das nie wieder.
• Kleines JSON zuerst. Bau den Parser gegen eine kurze, feste Beispielantwort im Code auf, bevor du ihn ans Netz hängst. So trennst du Parser-Fehler sauber von Netzwerkfehlern.
• Nur das nehmen, was du brauchst. Filter statt großer Dokumente – das spart Heap und macht den Sketch schneller.
• Werte mitschreiben. Mit einem Micro-SD-Modul hast du nach einer Woche eine Datei, aus der du echte Verläufe zeichnen kannst – siehe Arduino Datenlogger mit Micro-SD-Karte.
• Zugangsdaten nicht fest verdrahten. Ein Captive Portal macht dein Gerät auch in fremden Netzen einsatzbereit, ohne neu zu flashen.
• Daten weiterverteilen statt nur anzeigen. Wer die geholten Werte per MQTT ins Smart Home schiebt, macht aus dem Display eine Datenquelle für alle Geräte im Haus.
• Ein Kondensator an der Versorgung. Der ESP32 zieht beim Senden kurzzeitig über 300 mA. Ein 470 µF Elko direkt am Board verhindert Brownouts genau in dem Moment, in dem die Anfrage rausgeht.