Einstieg
Die Schnittstelle ist eine gewöhnliche REST-API über JSON.
Basisadresse
https://zeit.example.de/api/v1/…Der Präfix api und die Version v1 stehen im Pfad. v1 ist die Vorgabe; sie darf entfallen, sollte es aber nicht — eine ausdrückliche Version überlebt die nächste.
Läuft die API hinter der Oberfläche, leitet diese /api/* weiter; nach außen genügt ein einziger Name. Siehe HTTPS einrichten.
Zwei Wege hinein
- JWT für angemeldete Sitzungen,
- API-Schlüssel im Kopffeld
X-API-Keyfür Maschinen.
Siehe Authentifizierung.
Die Schnittstellenbeschreibung
Unter /api/docs liegt eine OpenAPI-Oberfläche mit jedem Endpunkt, jedem Feld und jeder Validierungsregel. Sie ist im Produktivbetrieb abgeschaltet, weil sie die gesamte Schnittstelle offenlegt; ENABLE_API_DOCS=true schaltet sie ein.
Sie ist die verbindliche Quelle. Dieses Handbuch beschreibt, wie die Endpunkte zusammenwirken; welche Felder ein Datensatz genau trägt, steht dort.
Was mit einer Anfrage geschieht
- Länge prüfen. Ein übermäßig langer Text wird abgewiesen, bevor er in die Verarbeitung gerät.
- Felder prüfen. Unbekannte Felder führen zu einem Fehler, statt stillschweigend verworfen zu werden — ein Tippfehler im Feldnamen wäre sonst eine Änderung, die nicht stattfindet, ohne dass es jemand merkt.
- Umwandeln. Zahlen und Wahrheitswerte werden aus Zeichenketten erkannt.
- Anmeldung und Rechte prüfen. Standardmäßig ist alles geschützt.
- Ratenbegrenzung. Siehe Taktsperre.
Statuscodes
| Code | Bedeutung |
|---|---|
| 200 / 201 | in Ordnung |
| 400 | die Anfrage ist fachlich nicht möglich — die Meldung sagt warum |
| 401 | nicht angemeldet, Token abgelaufen oder Schlüssel ungültig |
| 403 | angemeldet, aber ohne das nötige Recht |
| 404 | nicht gefunden — auch, wenn es zu einem fremden Mandanten gehört |
| 409 | jemand war schneller; Liste neu laden |
| 429 | Taktsperre |
| 503 | Modul nicht lizenziert, oder die Anwendung trägt gerade nicht |
Die Meldungen bei 400 sind auf Deutsch und für Menschen geschrieben. Sie nennen, was zu tun ist, nicht nur was falsch war — „Bitte die bestehende Buchung ändern statt eine zweite anzulegen“ statt „constraint violation“.
Zeitpunkte
Zeitpunkte werden als ISO-8601 entgegengenommen und geliefert. Reine Datumsangaben sind dort erlaubt, wo ein Tag gemeint ist (JJJJ-MM-TT).
Was Nacht, Sonntag und Feiertag ist, rechnet der Server in der Zeitzone des Beschäftigungsortes aus. Die Buchungsliste liefert die Zone je Zeile mit, damit der Aufrufer nicht raten muss.
Mandanten
Jede Sitzung gehört zu genau einem Mandanten; er steht im Token beziehungsweise am API-Schlüssel. Es gibt keinen Weg, über die Schnittstelle einen anderen zu erreichen.