Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Nutzung von XML RPC, Remote Script, JSON RPC, XMLAPI

Moderator: Co-Administratoren

Antworten
methodus
Beiträge: 67
Registriert: 05.07.2011, 20:17

Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Beitrag von methodus » 21.02.2019, 21:54

Hallo,

da mich über die Jahre hinweg die Onboard-Oberfläche der CCU stark genervt hat, habe ich begonnen mir (noch) ein alternatives Frontend, welches Progressive Web App-Konzepte mitbringt und speziell mobile first funktionieren soll.

Meine Intention es nochmal von Geburt an zu machen, war begründet durch:
- fehlende Funktionalitäten in der XML-API (z.B. Anlernen von neuen Geräten, dadurch muss ich mich wieder in das hässliche UI anmelden)
- XML setzt auf fast allen Plattformen zusätzliche Bibliotheken voraus; JSON ist hier wesentlich effizienter
- die Homematic API nutzt ein veraltetes JSON-RPC-Protokoll
- auch die API ist unvollständig
- über verschiedene Quellen und Funktionen sind in der CCU mögliche Schnittstellen verstreut, die sich nicht einheitlich nutzen lassen.

Ziel ist also eine standardisierte, plattformunabhängige und flexible Schnittstelle zu schaffen, die gleichzeitig leicht zu verwenden ist. Und wer sich mit Schnittstellenentwicklung auskennt, wird schnell bei Swagger/OpenAPI landen. Und so ist es:

Das Homematic OpenAPI 3.0 API-Plugin!

Projekt in GitHub:
https://github.com/methodus/homematic_openapi

OpenAPI 3.0 Spec bei SwaggerHub
https://app.swaggerhub.com/apis/methodu ... _api/0.0.1

Wie man an den Operationen erkennen kann, ist momentan noch nicht viel möglich, aber ich hoffe auf eure Kollaboration während der Entwicklung.

Zunächst möchte ich die API der XML-API weitgehend abdecken und anschließend die Homematic API, danach kommen die Funktionen, die irgendwo in der CCU verstreut sind.

Das gute an der OpenAPI: sie lässt sich in vielen Tools importieren und Clients für nahezu alle Programmiersprachen generieren.

Ich freue mich auf eure Kommentare

hobbyquaker
Beiträge: 3978
Registriert: 12.07.2009, 20:01
Hat sich bedankt: 17 Mal
Danksagung erhalten: 176 Mal
Kontaktdaten:

Re: Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Beitrag von hobbyquaker » 21.02.2019, 22:10

Sieht interessant aus!
Hab im Moment mit meinen eigenen Projekten viel zu tun, aber sobald ich da etwas Luft hab werd ich es installieren und genauer anschauen.
Ein Gedanke der mir als erstes kam: Ich würde vorschlagen direkt eine Authentifizierung zu implementieren, mittlerweile ist es machbar gegen die Rega zu Authentifizieren so dass die gleichen Credentials wie auch bei der Anmeldung am WebUI genutzt werden können (dafür steht ein UDP listener auf dem Loopback auf Port 1998 zur Verfügung, Beispielcode siehe https://github.com/HM-RedMatic/RedMatic ... ga-auth.js). Auch möglich wäre es eine lighttpd config mitzugeben die das bewerkstelligt (ein lighttpd module für basic auth an der rega ist in aktuellen CCU3/RaspberryMatic Firmwares an Bord).

methodus
Beiträge: 67
Registriert: 05.07.2011, 20:17

Re: Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Beitrag von methodus » 21.02.2019, 22:30

Die Auth steht bei mir noch ganz oben auf der ToDo-Liste. Ich wollte mir die Lösung von der Homematic API abschauen, die das gleich nach Access Level kategorisiert, aber da bin ich noch unschlüssig.

Jedenfalls würde ich hierfür einen extra Auth-Header oder Cookie erwarten, da das am besten passen sollte.

Da ich bei mir einen Reverse-Proxy mit OpenIDC im Einsatz habe, ist Auth im internen Netz für mich gerade nicht so relevant. Ziel wäre es schon, dass ich OpenID Connect an die Homematic angebunden bekomme, so dass ich mich ggf. gleich mit meinem Google-Account samt Session-Refresh anmelden kann, das ist aber ein anderes Projekt

methodus
Beiträge: 67
Registriert: 05.07.2011, 20:17

Re: Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Beitrag von methodus » 12.03.2019, 22:36

Ich habe mal ein erstes Release 0.1.0 eingestellt. Es sind inzwischen über 30 API Resourcen verfügbar. Weitere sollen nahtlos folgen.

https://github.com/methodus/homematic_o ... /tag/0.1.0

Die API nutzt die gleichen Login-Credentials wie die CCU selbst. Die Berechtigungsstufen orientieren sich an der Homematic API.

Aktuell wird für POST/PATCH requests noch x-www-url-formencoded als Content-Type verwendet, da sich das am leichtesten parsen lässt (weil identisch zum Parsen von Query-Parametern), aber JSON soll noch folgen.

Für meine Zwecke tut die API bereits, was ich brauche.

Vielleicht findet sich noch jemand, der das Plugin testen könnte.

hobbyquaker
Beiträge: 3978
Registriert: 12.07.2009, 20:01
Hat sich bedankt: 17 Mal
Danksagung erhalten: 176 Mal
Kontaktdaten:

Re: Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Beitrag von hobbyquaker » 13.03.2019, 17:25

Pass auf dass Du keine Code Injection Lücke aufmachst mit der $sid Variable, das sieht gefährlich aus hier: https://github.com/methodus/homematic_o ... on.tcl#L74
Am besten auf korrekte Länge und gültigen Zeichenvorrat regexen.

methodus
Beiträge: 67
Registriert: 05.07.2011, 20:17

Re: Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Beitrag von methodus » 13.03.2019, 21:08

Danke für den Hinweis, die Prüfung war vorher drin, aber war fehlerhaft, offenbar ist die dann beim Debuggen flöten gegangen.

Weißt du eventuell, wie und wo der Login-Prozess umgesetzt ist? Also wohin schickt die login.htm seine POST Daten? Irgendein Script muss ja die Session erzeugen...

Benutzeravatar
Psi
Beiträge: 512
Registriert: 09.08.2018, 19:58
Wohnort: Nürnberg
Hat sich bedankt: 27 Mal
Danksagung erhalten: 90 Mal

Re: Projektvorstellung: OpenAPI 3.0 Addon für die CCU

Beitrag von Psi » 24.03.2019, 00:09

/me is interested.

Du bist nicht der einzige, der die UI fürchterlich findet :)

Antworten

Zurück zu „Softwareentwicklung von externen Applikationen“