Die REST API von Wise Timetable

Sie können es sich sofort ansehen

Die Dienstbeschreibung benötigt keine Zugangsdaten, sodass die erste Frage, die eine Entwicklerin oder ein Entwickler stellt, in einer Zeile zu beantworten ist.

GET https://wise-tt.com/api/v2/meta liefert den Dienstnamen, die Version und die Liste der Endpunkte, die der Server derzeit bereitstellt. Kein Token, kein Konto, kein Verkaufsgespräch — öffnen Sie es in einem Browser. Es ist auch der ehrliche Weg, alles zu entdecken, was nach der letzten Überarbeitung des Handbuchs hinzugekommen ist.

Das Integrationshandbuch ist vollständig und ohne Formular veröffentlicht, mit den Parametern jedes Endpunkts, einer realistischen Beispielantwort für jeden und vollständigen funktionierenden Beispielen in curl, Python, JavaScript und C. Wir veröffentlichen es, weil eine Integration, die auf dem Papier machbar aussieht und es dann nicht ist, im dritten Monat eine weit teurere Entdeckung ist.

Das Lesen von Daten erfordert tatsächlich ein API-Konto, das wir ausstellen und das auf die Schulen beschränkt ist, die es lesen darf. Dieser Teil ist Absicht: Ein Stundenplan nennt, wer was lehrt und welche Studierenden daran teilnehmen.

Was die API bereitstellt

• Stundenpläne, nach Studierendengruppe, Lehrperson, Raum oder Lehrveranstaltung — oder für die ganze Schule auf einmal
• Vollständige Details zu einer einzelnen Veranstaltung, einschließlich der Hierarchie aus Studiengang, Jahrgang, Zweig und Gruppe hinter jeder teilnehmenden Gruppe
• Die Grenzen des veröffentlichten Studienjahres, damit ein Client verhindern kann, dass Nutzende in Wochen navigieren, die keine Daten enthalten können
• Feiertage, damit ein leerer Tag als Feiertag gelesen wird und nicht als fehlende Daten
• An eine Schule, eine Gruppe, eine Lehrveranstaltung oder eine Lehrperson gebundene Benachrichtigungen, dedupliziert und als strukturierte Objekte zurückgegeben
• Codelisten für Studiengänge, Zweige, Gruppen, Lehrende, Räume und Lehrveranstaltungen — die IDs und Bezeichnungen, aus denen eine Auswahlliste gebaut wird
• Raumkapazität, Raumcode und das eigene Raumpostfach der Schule, wo die Schule sie ausgefüllt hat
• Der Klingelplan der Schule, weil Zeitfensterlängen nicht überall gleich sind
• Die eigenen Wochennummern der Schule und die eigene Bezeichnung der Schule für eine Woche, wo sie eine hat — eine Wochennummer ist in diesem Produkt nicht die ISO-Woche des Kalenderjahres, und kein Client sollte je eine berechnen
• Die Buchungsarten, die eine Schule verwendet, und die Räume, die jede Lehrperson reservieren darf, für einen Client, der außer dem Lesen auch Buchung anbietet
• Was jede Schule einem Client anzubieten erlaubt, sodass eine Auswahlliste zum Durchsuchen nach Lehrenden dort ausgeblendet wird, wo Lehrverpflichtungen vertraulich behandelt werden
• Anwesenheitslisten, wo eine Einrichtung Anwesenheit per QR-Code erfasst — die Liste jeder Veranstaltung vollständig, nach Daten für eine Erstbefüllung und danach das, was sich seit dem letzten Aufruf geändert hat, für ein Studierendeninformationssystem. Personenbezogene Daten von Studierenden, daher liest ein Konto sie nur mit einer eigenen Berechtigung

Raumbuchungen, von einer Person statt von einem Konto vorgenommen

Die Buchung ist der einzige Teil der API, der überhaupt kein Integrationskonto benötigt, und der Grund verdient eine klare Nennung: Eine Buchung wird von jemandem vorgenommen, und der Stundenplan hält fest, von wem. Eine beschäftigte Person meldet sich mit eigenem Benutzernamen und Passwort an, erhält ein Token, das eine Schule benennt und acht Stunden gilt, und legt Buchungen als sie selbst an, ändert und löscht sie — weshalb auch eine in eine veröffentlichte App einkompilierte Zugangsberechtigung diese Oberfläche nie erreichen kann.

Bevor etwas geschrieben wird, kann ein Client fragen, ob ein Muster frei ist. GET /v2/free-busy entfaltet jeden zweiten Dienstag von März bis Mai, 08:00–10:00, Raum B-004 in reale Daten und meldet Datum für Datum, was bereits im Weg steht — und ob es der Raum, die Lehrperson oder die Gruppe ist. Ein Konflikt wird mit den kollidierenden Daten abgelehnt statt mit einem pauschalen Nein, zusammen mit den nächstgelegenen Anfangszeiten und den anderen Räumen, die an jedem dieser Daten frei sind. Eine planende Person, die es ernst meint, kann trotzdem über den Konflikt hinweg buchen, und das wird als bewusste Entscheidung festgehalten statt verborgen.

Die gesamte Oberfläche — eine Person anmelden, die Buchungsarten der Schule, die Raum-Whitelist jeder Lehrperson, Verfügbarkeit sowie das Anlegen, Ändern und Löschen einer Buchung — ist Kapitel 13 des Handbuchs, mit einem durchgespielten Beispiel von der Anmeldung bis zum gebuchten Raum.

Gebaut für einen Client, der abfragt

Jede Antwort trägt einen ETag. Wiederholen Sie die Anfrage mit If-None-Match, und ein unveränderter Stundenplan antwortet mit 304 ganz ohne Rumpf, was der Normalfall für einen Bildschirm im Foyer ist, der alle paar Minuten aktualisiert. Ein wohlerzogener Client überträgt an einem ruhigen Tag fast nichts.

Zugangsdaten werden einmal gegen ein Bearer-Token getauscht, das 24 Stunden gilt und die Schulen kodiert, die es lesen darf. Browser-Anwendungen werden über eine explizite Origin-Allowlist statt eines Platzhalters unterstützt — nennen Sie uns den Origin, von dem Ihr Dashboard ausgeliefert wird, und er wird hinzugefügt.

Die ältere Oberfläche wird weiter ausgeliefert und bleibt eingefroren

Einrichtungen, die gegen die frühere API integriert haben, mussten durch v2 keinen Bruch ihrer Integration hinnehmen. Die Legacy-Pfade werden weiter ausgeliefert und sind absichtlich eingefroren, und v2 behält absichtlich die Legacy-Feldnamen bei — sodass der Wechsel zu v2 eine Änderung der URL und keine Änderung des Parsers ist und die von v2 hinzugefügten Felder Ergänzungen und keine Ersetzungen sind.

Das ist die ganze Richtlinie in einem Satz: Eine API, gegen die eine Hochschule baut, ist ein Versprechen, und es zu brechen, um Feldnamen aufzuräumen, ist keine Ersparnis.