Einfacher Zugriff auf Ihre Energiedaten

Mit der REST API können externe Anwendungen auf ausgewählte Daten und Funktionen des Systems zugreifen. Dadurch lassen sich beispielsweise Energiedaten in eigene Anwendungen integrieren, Berichte automatisiert erstellen oder Daten mit anderen Systemen austauschen.

Die API folgt etablierten REST-Standards und verwendet JSON als Datenaustauschformat. Dadurch kann sie von nahezu jeder Programmiersprache und Integrationsplattform genutzt werden. 

Authentifizierung

Der Zugriff auf die REST API ist geschützt. Für jede Anfrage muss sich der aufrufende Client authentifizieren. Die API verwendet hierzu einen API-Schlüssel (API Key). Geschützte Endpunkte können nur mit gültigen Anmeldedaten aufgerufen werden.

API-Schlüssel erzeugen

Zum gegenwärtigen Zeitpunkt befindet sich die API noch im Beta-Stadium, sodass die Erzeugung von API-Schlüsseln noch nicht frei zugänglich ist. Dennoch wollen wir die grundsätzliche Funktionsweise bereits jetzt erklären. 

API-Schlüssel verwenden

Der API-Schlüssel wird bei Anfragen im HTTP-Header "X-API-Key" übertragen. Ohne gültige Authentifizierung wird die Anfrage von der API abgewiesen. Bewahren Sie Ihren API-Schlüssel daher vertraulich auf und geben Sie ihn nicht an Dritte weiter.

Schnittstellenbeschreibung mit OpenAPI

Für jede API-Version stellt die Anwendung ein OpenAPI-Dokument bereit. Dieses Dokument beschreibt die gesamte Schnittstelle maschinenlesbar und dient gleichzeitig als technische Referenz für Integratoren.

Das OpenAPI-Dokument enthält unter anderem:

• verfügbare Endpunkte
• unterstützte HTTP-Methoden
• erforderliche Parameter
• Datenstrukturen für Anfragen und Antworten
• mögliche Fehlercodes
• Beschreibungen der einzelnen Funktionen

Für jede unterstützte API-Version steht eine eigene OpenAPI-Beschreibung zur Verfügung. Beispiel (wobei hier v4 exemplarisch für Version 4 der API steht):

Viele Entwicklungswerkzeuge können OpenAPI-Dateien direkt einlesen. Dadurch können Entwickler:

• die API komfortabel erkunden,
• Client-Bibliotheken automatisch erzeugen,
• Datenmodelle generieren,
• Integrationen schneller umsetzen.

API-Versionierung

Die REST API wird versioniert bereitgestellt. Dadurch bleiben bestehende Integrationen auch dann funktionsfähig, wenn neue API-Versionen veröffentlicht werden. Änderungen, die bestehende Anwendungen beeinträchtigen könnten, werden in einer neuen Version bereitgestellt. Ältere Versionen bleiben für einen definierten Zeitraum verfügbar und werden im Anschluss abgeschaltet.

Wir empfehlen, neue Integrationen stets gegen die aktuellste API-Version zu entwickeln und bestehende Integrationen regelmäßig auf neuere Versionen umzustellen.

Streaming

Für eine besonders schnelle Bereitstellung Ihrer Energiedaten unterstützt die API bei ausgewählten Funktionen das Streaming von Daten. Statt auf die vollständige Übertragung einer großen Datenmenge zu warten, werden Ergebnisse Schritt für Schritt bereitgestellt. So können Daten bereits angezeigt oder weiterverarbeitet werden, während die Übertragung noch läuft.

Dadurch profitieren Sie von kürzeren Wartezeiten, einer besseren Benutzererfahrung und einer effizienten Verarbeitung auch sehr großer Datenbestände.

Neben dem Standardformat JSON werden folgende Formate verarbeitet und ausgegeben, die im Accept-Header angefordert und übertragen werden können: