Integration · API
Absichtlich langweilig.
REST über HTTPS, JSON rein und raus, datierte Versionen, idempotente Schreibzugriffe und Fehler, die Ihnen sagen, welches Feld falsch war. Über die Ressourcen hinaus gibt es hier nichts zu lernen — so ist es gemeint.
- RESTüber HTTPS
- 24 hIdempotenzfenster
- 90 TageVorlauf bei Abkündigung
Vertrag
Die Teile, auf die Sie sich verlassen werden
- Versionierung
- Datiert, je Schlüssel festgelegt
- Idempotenz
Idempotency-Key, 24 Stunden- Fehler
- Feldgenau, maschinenlesbar
- Ratenbegrenzung
- Je Schlüssel, Header in jeder Antwort
- Authentifizierung
- Bearer-Schlüssel, nur serverseitig
- Uhr
- UTC, RFC 3339
Ein Schlüssel ist an eine Version gebunden. Neue Versionen erreichen Sie erst, wenn Sie wechseln, und eine Version wird mindestens 90 Tage nach Ankündigung ihrer Nachfolgerin weiter unterstützt.
Ein wiederholtes Anlegen liefert die ursprüngliche Prüfung. Ein Wiederholungssturm während eines Vorfalls kann keine fünf Prüfungen gegen einen Spieler eröffnen.
Ein 422 nennt das Feld und die verletzte Regel. Nichts liefert ein nacktes 400 mit Prosa im Rumpf.
Rest und Zurücksetzzeitpunkt sind immer enthalten — ein Client kann also langsamer werden, bevor man ihn stoppt.
Schlüssel erreichen nie einen Browser oder ein Mobilgerät; der Client erhält stattdessen kurzlebige Schritt-Token.
Jeder Zeitstempel in jedem Datenpaket und jedem Nachweispaket, ohne Varianten in Ortszeit.
Ressourcen
Die Oberfläche, vollständig
| Methode und Pfad | Tut | Idempotent |
|---|---|---|
POST /v1/checks | Eröffnet eine Prüfung für eine Person in einem Markt | Ja, 24 h |
GET /v1/checks/{id} | Aktueller Zustand, Ergebnis und Gründe | — |
POST /v1/checks/{id}/cancel | Bricht eine Prüfung ab, die noch erfasst | Ja |
GET /v1/evidence/{id} | Das versiegelte Paket hinter einem Ergebnis | — |
GET /v1/events | Das Journal, für alles, was ein Webhook nicht zustellen konnte | — |
POST /v1/policies | Veröffentlicht eine Richtlinienversion für einen Markt | Ja |
POST /v1/exclusions | Veröffentlicht Ihre Sperrdatei, wo Sie die maßgebliche Stelle sind | Ja |
Sieben Ressourcen. Eine Prüf-API, die mehr braucht, legt meist ihre eigene innere Struktur offen statt Ihr Problem.
Entscheidungen
Warum sie so geschnitten ist
Warum wird die Antwort nicht gestreamt?
Weil der langsame Teil der Spieler ist, nicht wir. Eine Prüfung wartet darauf, dass ein Mensch seinen Pass findet; dafür eine Verbindung offen zu halten, kostet Sie etwas und macht es für beide brüchig. Genau dafür gibt es den Webhook.
Warum enthält das Ergebnis keinen Score?
Es enthält Werte für die einzelnen Signale, im Nachweispaket. Was es nicht tut: sie auf eine einzige Zahl zusammenziehen — denn die einzelne Zahl ist genau das, was sich einer Aufsicht hinterher nicht erklären lässt.
Können wir einer Prüfung nachträglich eine Richtlinie zuordnen?
Nein. Eine Prüfung hält die Richtlinienversion fest, die sie entschieden hat, und dieser Eintrag ist unveränderlich. Eine Neuentscheidung unter neuer Richtlinie eröffnet eine neue Prüfung, die auf die alte verweist.