Untis API Übersicht

DATEN!!!

Um die App richtig zum laufen zu bringen - das heißt einen Stundenplan abfragen, Vertretungstexte, Ausfall anzuzeigen, Ferien etc. - benötigt man gewisse Daten die man über eine vorhandene API von Untis abfragen kann.

Nach anfrage stellt Untis offiziell keine Dokumentation zur API zur Verfügung. Folgende punkte führten aber dazu, dass es doch möglich war die Daten vom Untis Server heraus zu kitzeln:

• Man benötigt keinen API Schlüssel! Alle Daten sind "Anonym" abrufbar (Einige benötigen jedoch einen Login vom User - ist ja klar)
• Zwar Sperrlich, aber es gab schon ein paar andere Projekte auf GitHub an denen sich man orientieren konnte. Z.B. hier
• Webscraping Skills

Protokolle

Die App benutzt insgesamt zwei verschiedene Varianten API anfragen zu stellen:

• JSON RPC 2.0 -> Ausführliche/Offizielle Dokumentation
• Einfacher HTTP Client

Beide Methoden sind in einem Weiteren Kapitel beschrieben Alle lassen sich mit einem einfachen TCP socket zu realisieren.

In diesem Kapitel wird erläutert, wie man die API nutzen kann um einfache bis komplexere Abfragen zu stellen. Anzumerken ist auch dass durch die mangelnde Dokumentation diese "Ersatz Dokumentation" keineswegs als vollständig zu betrachten ist.

JSONRPC Basics

Eine offizielle und ausführliche Dokumentation zu JSON RPC 2.0 befindet sich hier

Basics

Ich schreibe hier trotzdem nochmal kurz die wichtigsten Punkte für eine Abfrage auf:

Format einer Server Anfrage

• JSON Format -> Erklärung
• es MUSS die Variable jsonrpc": 2.0 gesendet werden
• Das Feld "method" beschreibt den Methodennamen der Daten die vom Server geliefert werden sollen z.B. "timetable"
• "params" beschreibt die Parameter die zusätzlich zur Methode gesendet werden sollen
• Es MUSS das Feld "id" existieren. Das kann z.B. der Name der App sein.

Beispiel einer einfachen Anfrage:

{
  "jsonrpc": "2.0", 
  "method": "login", 
  "params": {
    "username": "Benutzername",
    "passwort": "Passwort"
  }, 
  "id": "tolleApp!"
}

So könnte eine Login Methode aussehen. Was der Server zurückliefern könnte ist in "Format einer Server Antwort" beschrieben.

Format einer Server Antwort

Eine Antwort kommt auch im JSON Format. Dabei sind standartmäßig folgende Werte enthalten:

• Das Feld jsonrpc": 2.0
• Die id die in der Anfrage mitgeschickt wurde. Im Beispiel "id": "tolleApp!"
• Die eigentlichen Daten die man auslesen möchte besitzten keinen standartisierten namen. Die Feldnamen und das Datenformat können sich je nach methodennamen ändern.

Beispiel einer Serverantwort:

{
  "jsonrpc": "2.0", 
  "errorMessage": "Benutzername oder Passwort falsch!", 
  "id": 1
}

Wie JSONRPC konkret in der App benutzt wird und welche Methoden es gibt, erfährst du jetzt

Umsetzung

Dieses Projekt ist open Source. Das bedeutet du und jeder andere darf sich den Code anschauen. In diesem Abschnitt möchte ich dir zeigen, wie das JSON RPC 2.0 Protokoll in die SOL-Connect App eingebaut wurde.