Wer die Commitlogs unseres Netzwerkverwaltungs und Monitoringportals Netmon aufmerksam verfolgt, dem wird aufgefallen sein, dass in Netmon aktuell eine neue Web API auf Basis des REST Standards entwickelt wird.
Ein bisschen konnten wir ja schon immer mit Netmon kommunizieren. Die Schnittstellen dafür bestehen aber nur aus einfachen CSV Strings was vorallem dem Umstand geschuldet ist, dass unsere Router bisher einfache Bash-Scripte nutzen um sich zu Netmon zu verbinden und das Parsen komplexer Datenstrukturen damit mindestens umständlich ist. Vor einiger Zeit haben wir uns dann entschieden, dass wir diese Scripte in Zukunft nach C/C++ portieren wollen.
Das eröffnet uns die Möglichkeit seitens der Router komplexere Datenstrukturen zu verarbeiten und damit auch seitens Netmon komplexere Datenstrukturen anzubieten ohne zwei verschiedene APIs dauerhaft warten zu müssen. Die Entwicklung der API steht noch am Anfang, jedoch möchte ich einen kleinen Teil hier bereits einmal vorstellen.
In Netmon und damit auch in der API gibt es verschiedenste Objekte. So gibt es Benutzer, IP-Adressen, Interfaces, Events und natürlich Router. Oftmals benötigt man aber nicht nur eines der Objekte, sondern eine ganze Liste an Objekten. Zum Beispiel alle Router. Und so gibt es neben den einzelnen Objekten auch noch eine ganze Reihe von Listen die eine Menge von Objekten enthalten, wie z.B. die Routerliste die ich im Folgenden vorstellen möchte.
Jede Antwort auf eine Anfrage an die API wird im XML Format zurückgeliefert und besteht aus einem Kopf, dem request-Element und einem Body, dem Element das die eigentlich spannenden Daten enthält und das nach dem Namen des Angefragten Objekts benannt ist.
Das Request Element enthält fünf weitere Elemente die einem Informationen über den Zustand der Anfrage liefern:
- authentication entsprich einem Boolean-Feld und kann die Werte 0 (Authentifizierung nicht erfolgreich) und 1 (Authentifizierung erfolgreich) annehmen. Im Falle der Routerliste ist der Wert i.d.R. immer 1, da zum Abrufen des Routerlist-Objekts keine Authentifizierung notwendig ist
- api_key nimmt den Wert des API-Keys an mit dem Man sich gegenüber der API authentifiziert hat. Im Falle des Routerlist-Objekts ist der API-Key leer, da zum Abrufen des Routerlist-Objekts wie bereits geschrieben keine Authentififizierung notwendig ist
- method enthält den Namen des Objekts das abgerufen wird und nimmt in diesem Fall den Wert routerlist an
- error_code ist im Erfolgsfall 0 und nimmt bei Fehlern den zu dem jeweiligen Fehler gehörenden Integer Wert an. Aktuell wird diese Funktion nicht verwendet
- error_message ist im Erfolgsfall leer, enthält bei Fehlern aber eine entsprechende Fehlermeldung
Den eigentlich spannenden Teil nimmt das Body-Element ein. Es enthält alle zu der angefragten Routerliste gehörenden Router-Elemente. Wichtig ist, dass die zurückgelieferte Routerliste aus Lastgründen nicht zwangsläufig alle zur der Routerliste gehörenden Router auch tatsächlich enthält sondern nur die Anzahl Router, die die API maximal für eine Anfrage zurückliefert. Damit der Anwender der API weiß, wie viele Router die Liste tatsächlich enthält und wie viele Elemente nur zurückgeliefert wurden, Enthält das Element Routerlist noch die folgenden Attribute:__
- total_count Anzahl der insgesamt in der Liste enthaltenen Elemente
- limit Anzahl der tatsächlich maximal zurückgelieferten Elemente
- offset Platz des ersten zurückgelieferten Elements in der Gesamtliste
Die Attribute offset und limit sind außerdem Parameter, die der Anfrage optional als GET-Parameter mitgegeben werden können. Mit ihrer Hilfe kann man sich nun über mehrer Anfragen die komplette Routerliste von der API abholen. Dazu später ein Beispiel.
Weitere optionale GET-Parameter sind die Parameter sort_by und order mit deren Hilfe man eine Liste nach einem bestimmten Element der Router-Elemente sortieren kann:
- sort_by Element nach dessen Wert sortiert werden soll (aktuell nur „hostname“ erlaubt)
- order Reihenfolge in der sortiert werden soll („asc“ für Aufsteigend und „desc“ für absteigend)
Eine Anfrage nach den Routern 0-10 aufsteigend nach Hostname sortiert ginge also an folgende URL: http://netmon.freifunk-ol.de/api/rest/routerlist/?offset=0&limit=10&sort_by=hostname&order=asc
Enthält die zurückgelieferte Liste nun eigentlich mehr als 10 Router, kann man sich die komplette Liste holen indem man mehrere Anfragen an die API stellt und den Wert des Parameters limit so lange in 10er Schritten erhöht bis er größer bzw. gleich dem Attribut total_count des Elements routerlist ist (andere Werte für limit als 10 sind möglich).
Schauen wir uns noch kurz die Router-Elemente der Routerliste an. Jedes Router-Element besteht natürlich aus einer ganzen Reihe weiterer Elemente die den Router spezifizieren. Dazu gehört die Router-ID, eine User-ID, der Hostname und weitere Elemente. Interessant ist insbesondere das Element statusdata. Das Element enthält die ständig aktualisierten Statusdaten eines Routers. Ferner enthält jedes Routerelement weitere Listen wie z.B. eine Liste der Interfaces des Routers eine Statushistorie usw. die aktuell noch nicht vollständig implementiert sind.
Die Große Frage lautet jetzt: was soll der Aufwand und was kann man mit der API jetzt schon machen? Erstens soll natürlich die Kommunikation mit den Routern und damit letztendlich auch die Benutzerführung bei der Inbetriebnahme eines Routers sowie die Wartung im laufenden Betrieb verbessert werden. Zweitens gibt es verschiedene Anwendungen, die nicht in Netmon direkt integriert werden sollen, da sie das System unnötig aufblähen würden, aber trotzdem die in Netmon gespeicherten Daten benötigen. Diese sollen die API in Zukunft als zentrale und verlässliche Schnittstelle nutzen können. Und drittens sollten die Daten einer einzelnen Community idealer Weise mit den Daten anderer Communities zusammengeführt werden können um so bspw. mit Hilfe der OpenWifiMap einen Überblick über alle Communities und Standorte gewinnen zu können.
Letzteres Beispiel, die OpenWifiMap, wäre auch ein erstes Anwendungsbeispiel das schon mit dem aktuellen Stand der API umgesetzt werden könnte. Also wenn jemand Lust und Zeit hat ein wenig mit der API zu experimentieren, darf das hier gerne als Einladung verstanden werden ein kleines Script zu entwickeln, dass sich regelmäßig die Routerliste aus der Netmon API holt und an die API der OpenWifiMap sendet. Die Dokumentation zur Netmon XML REST API kann hier eingesehen wärend die Dokumentation zur API der OpenWifiMap hier eingesehen werden kann. Sollten wärend der Entwicklung Probleme bei der Handhabung der Netmon API auftreten, können diese hier in unserem Ticketsystem gemeldet werden. Ansonsten steht Entwicklern natürlich auch die Entwicklermailingliste von Freifunk Oldenburg offen.