Der-OnlineStundeplan.de. API-Dokumentation. Der-OnlineStundenplan.de 1 Version 1.1

Transkript

1 Der-OnlineStundeplan.de API-Dokumentation Der-OnlineStundenplan.de 1 Version 1.1

2 Schulen Liste aller Schulen GET /api/v1/school "schools": "name":"rvwbk","city":"paderborn","website":" "name":"demo","city":"musterstadt","website":" Gibt ein JSON-Objekt zurück, das alle unterstützen Schulen enthält. Im schools Array befinden sich alle Schulen im System. Jede Schule hat die Attribute name, city und website. Will Change: Es soll ein weiteres Attribut mit der Bezeichnung longname hinzugefügt werden. Es soll den vollen offiziellen Namen einer Schule enthalten. Beispiel: "RvWBK" - "Richard von Weizsäcker Berufskolleg Paderborn" Infos einer Schule GET /api/v1/school/$schoolname "name": "RvWBK", "city": "Paderborn", "website": " Gibt ein JSON-Objekt zurück das alle Informationen der gegebenen Schule enthält. Die Attribute success, name, city und website werden übergeben. Will Change: Es soll ein weiteres Attribut mit der Bezeichnung longname hinzugefügt werden. Es soll den vollen offiziellen Namen einer Schule enthalten. Beispiel: "RvWBK" - "Richard von Weizsäcker Berufskolleg Paderborn" Es soll ein weiteres Attribut mit der Bezeichnung logo hinzugefügt werden. Es soll eine URL zum Logo der Schule enthalten. Der-OnlineStundenplan.de 2 Version 1.1

3 Liste aller Klassen einer Schule GET /api/v1/school/$schoolname/class "classes": "AVA51", "AVT51", "AVT52", "TMV41", "TMV51" Gibt ein JSON-Objekt zurück, das alle Klassen der gegebenen Schule enthält. Das Attribut classes enthält ein Array mit allen Klassen der Schule in alphabetischer Sortierung. Stundenplan Stundenplan einer Klasse der aktuellen Woche GET /api/v1/school/$schoolname/class/$classname "week": 8, "last_updated": " :26:57", "timetable": Gibt ein JSON-Objekt zurück, das den Stundenplan der aktuellen Woche der gegebenen Klasse enthält. An Werktagen (Montag-Samstags) wird die Kalenderwoche nach ISO-8601 angenommen. Sonntags wird automatisch die nächste Woche ausgewählt. Für viele Schüler währe es sinnvoll bereits Samstags den Stundenplan der nächsten Woche angezeigt zu bekommen, jedoch gibt es einige Schulen/Schüler die auch Samstags Unterricht haben. Neben den Stundenplandaten im timetable Attribut wird noch die Kalenderwoche des Stundenplans im Attribut week mitgegeben. Das Datum und die Uhrzeit der Stundenplanaktualisierung steht im Attribut last_updated. Der-OnlineStundenplan.de 3 Version 1.1

4 Stundenplan einer Klasse der aktuellen Woche GET /api/v1/school/$schoolname/class/$classname/$week "week": 9, "last_updated": " :26:57", "timetable": Gibt ein JSON-Objekt zurück, das den Stundenplan enthält. Ist $WEEK 0 so wird die aktuelle Woche angenommen. Die aktuelle Kalenderwoche wird wie beim Aufruf ohne $WEEK berechnet. $WEEK kann einen positiven oder negativen ganzzahligen Wert haben. Dieser wird zu der aktuellen Kalenderwoche addiert. Neben den Stundenplandaten im timetable Attribut wird noch die Kalenderwoche des Stundenplans im Attribut week mitgegeben. Das Datum und die Uhrzeit der Stundenplanaktualisierung steht im Attribut last_updated. Stundenplan einer Klasse der aktuellen Woche GET /api/v1/school/$schoolname/class/$classname/fixedweek/$week "week": 3, "last_updated": " :26:57", "timetable": Gibt ein JSON-Objekt zurück, das den Stundenplan der angegebenen Kalenderwoche enthält. Neben den Stundenplandaten im timetable Attribut wird noch die Kalenderwoche des Stundenplans im Attribut week mitgegeben. Das Datum und die Uhrzeit der Stundenplanaktualisierung steht im Attribut last_updated. Der-OnlineStundenplan.de 4 Version 1.1

5 Liste der Verfügbaren Wochen einer Klasse GET /api/v1/school/$schoolname/class/$classname/listweeks "availableweeks": -10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3 Gibt ein JSON-Array zurück, das die relativen Wochennummern der verfügbaren Klassen zurückgibt. Liste der Verfügbaren Wochen einer Klasse GET /api/v1/school/$schoolname/class/$classname/fixedweek/listweeks "availableweeks": "1", "2", "3", "4",, "11", "12", "13", "14" Gibt ein JSON-Array zurück, das die relativen Wochennummern der verfügbaren Klassen zurückgibt. Der-OnlineStundenplan.de 5 Version 1.1

6 Das Stundenplanformat Der Stundenplan besteht aus einem JSON Objekt. Dieses JSON Objekt enthält zwei Objekte: times und days. Das erste Array hat den Schlüssel times. Es repräsentiert die erste Spalte des Stundenplans. Im falle des Richard von Weizsäcker Berufskollegs sind dort die Stunden nur durchnummeriert. Es gibt jedoch auch Schulen bei denen dort die Zeiten stehen. Das Array days enthält die einzelnen Tage mit den zugehörigen Stunden. Die Tage sind Objekte mit zwei Attributen: name und data. Im Attribut name ist die Überschrift des Tages. Im Beispiel des Richard von Weizsäcker Berufskollegs besteht diese Überschrift aus dem Wochentag und einem Datum ohne Jahr. Im Attribut data ist für jede Stunde ein Array vorhanden. Jede Stunden enthält mindestens ein Array aus Strings. Bei normalen Stunden ist ein Array mit den einzelnen infos zur Stunde enthalten. Eine Stunde kann bei mehreren Lehrern in Unterschiedlichen Räumen stattfinden (z.b. bei geteilten Klassen). Üblicherweise sind solche Stunden höchstens 2 geteilt, in Sonderfällen gibt es jedoch auch 4 Teile. Normalerweise beinhaltet das Stundenarray 3 Strings die Lehrer, Raum und Fach angeben. "week": 8, "last_updated": " :26:57", "timetable": "times": "1", "2",,"13", "14", "days": "name": "Montag 22.2.", "data": "", "HOO.", "D134C", "DIFF", "KEH", "D128C", "DIFF", "HOO.", "D134C", "DIFF", "KEH", "D128C", "DIFF", "RIP", "D128C", "AE", "",, "name": "Samstag 27.2.", "data": "", "", Der-OnlineStundenplan.de 6 Version 1.1

7 Fehlerbehandlung Aufbau der Fehlermeldungen Anders als bei einer erfolgreich verarbeiteten Anfrage wird im Fehlerfall das success flag auf false gesetzt. Es wird ein errorcode und eine errormessage spezifiziert. Die errormessage ist eine kurze Beschreibung in Englisch die beim entwickeln helfen soll. Es ist empfohlen ausführlichere, lokalisierte Texte mit dem errorcode zu verknüpfen um dem Benutzer eine bessere "User Experience" zu bieten. Die Error Codes sind gruppiert. Fehler die mit den Nummern 1X hängen mit der Schule zusammen, die Fehler mit den Nummern 2X hängen mit der Klasse zusammen und die Fehler mit der Nummer 3X hängen mit der Woche zusammen. Keine Schulen gefunden "success":false, "errorcode":10, "errormessage":"no Schools Found" Diese Fehlermeldung sollte nicht erscheinen, denn sie bedeutet das es keine Schule mehr im System gibt. Angegebene Schule nicht gefunden "success":false, "errorcode":11, "errormessage":"unknown School" Die angegebene Schule kann nicht gefunden werden. Eingabe mit der Liste der Schulen abgleichen. Angegebene Klasse nicht gefunden "success":false, "errorcode":20, "errormessage":"unknown Class" Die angegebene Klasse wurde nicht gefunden. Eingabe mit der Liste der Klassen abgleichen. Der-OnlineStundenplan.de 7 Version 1.1

8 Stundenplan der Woche nicht gefunden "success":false, "errorcode":30, "errormessage":"week not available" Der Stundenplan der angegeben Woche konnte nicht gefunden werden. Achtung diese Fehlermeldung kann auch auftreten wenn keine Woche explizit angegeben wurde! Sollte ein Stundenplan beispielsweise nicht rechtzeitig von der Schule online gestellt werden kann es vorkommen das die relative Woche 0 nicht verfügbar ist. Changelog Version 1.1 vom Rechtschreibfehler korrigiert, Fehlerbehandlung hinzugefügt Version 1.0 vom Initiale Dokumentation Der-OnlineStundenplan.de 8 Version 1.1