So funktioniert die Optifora-API
Diese Seite beschreibt die Gestalt der API: wie Identität nachgewiesen wird, wie Versionen fortschreiten, innerhalb welcher Grenzen eine Anfrage bleibt, wie ein Fehler aussieht und wie Daten mit der Außenwelt ausgetauscht werden.
Das Produkt befindet sich in der Entwicklung, und die API-Oberfläche wird noch vervollständigt. Ein Referenzdokument zu den Endpunkten wird gesondert veröffentlicht; diese Seite enthält weder Adressen noch Beispielaufrufe, sondern nur die Mechanik.
Authentifizierung
Jede Anfrage gehört entweder zu einer Person oder zu einer registrierten Anwendung. Eine Anfrage ohne Identität, die auf einen geschützten Endpunkt trifft, kommt als nicht authentifiziert zurück.
- Bearer-TokenDas Zugriffstoken wird im Autorisierungs-Header der Anfrage übertragen. Es ist signiert und sagt nur aus, wem die Anfrage gehört.
- Kurze LebensdauerEin Zugriffstoken läuft nach einer in Minuten gemessenen Frist ab; die Länge ist eine Einstellung der Installation und beträgt standardmäßig dreißig Minuten.
- Erneuerung und RotationEine Sitzung wird über ein Refresh-Token verlängert, und jede Verlängerung gibt ein neues Paar aus. Wird ein bereits verbrauchtes Refresh-Token ein zweites Mal vorgelegt, werden sämtliche Sitzungen dieser Person entzogen.
- Berechtigungen sind nicht ins Token eingebackenDas Token trägt allein die Identität; was eine Person sehen darf, wird bei jeder Anfrage bei der Datenbank erfragt. Eine entzogene Berechtigung greift deshalb schon, bevor das vorhandene Token abläuft.
- IntegratorschlüsselEine registrierte Anwendung verbindet sich mit ihrem eigenen Schlüssel. Der Klartextwert wird nur einmal angezeigt, bei der Erstellung; gespeichert werden sein Hashwert und das nicht geheime Präfix, an dem sich ein Schlüssel wiedererkennen lässt.
- Die Organisation erteilt den ZugriffWie verbreitet eine Anwendung auch sein mag: ohne eine von der Organisation erteilte und dokumentierte Freigabe sieht sie keine einzige Zeile. Die Freigabe ist datiert, im Umfang begrenzt und jederzeit widerrufbar.
Versionierung
- Die Version steht im PfadEndpunkte werden hinter einem Versionspräfix veröffentlicht; die heutige Oberfläche ist Version eins.
- Eine brechende Änderung eröffnet einen neuen PfadDer Vertrag eines bestehenden Endpunkts wird nicht im laufenden Betrieb gebrochen. Eine inkompatible Änderung wird auf einem neuen Versionspfad veröffentlicht, während der alte weiterläuft.
- Das Dokument nennt seine eigene VersionDie Referenz trägt die Versionsnummer, aus der sie erzeugt wurde; welche Version Sie lesen, beantwortet das Dokument selbst.
Umgebungen und Grenzen
Die Referenz benennt zwei Umgebungen: Produktion und lokale Entwicklung. Die Basisadresse wird einem Integrator zusammen mit seinem Schlüssel übergeben; auf dieser Seite wird sie nicht veröffentlicht.
- Betriebsbereitschaft und Verkehrsbereitschaft werden getrennt gemessenEin Endpunkt meldet, dass der Prozess läuft; der zweite schickt eine echte Abfrage an die Datenbank und bestätigt deren Erreichbarkeit. Nur der zweite entscheidet, ob Datenverkehr geschickt werden soll.
- Browser-Ursprünge sind auf eine Liste beschränktUrsprungsübergreifende Anfragen werden nur von vorab hinterlegten Ursprüngen angenommen; solange die Liste leer ist, wird eine ursprungsübergreifende Browseranfrage abgewiesen.
- Größenbegrenzung des RumpfesDer Rumpf einer Anfrage darf fünf Megabyte nicht überschreiten. Große Datenmengen laufen als Sammelübertragung mit eigenem Statusdatensatz, nicht als einzelne Anfrage.
- Geheimnisse werden nicht ins Protokoll geschriebenIm Serverprotokoll werden weder Autorisierungs-Header noch Cookies, Passwörter oder nationale Identifikationsnummern aufbewahrt.
Ratenlimit
Das Limit gilt je Adresse und je Minute. Der Standardwert liegt bei 120 Anfragen pro Minute und wird bei der Installation festgelegt. Der Rest wird bei jeder Antwort in Headern gemeldet.
| Antwort-Header | Aussage |
|---|---|
| x-ratelimit-limit | Das gesamte Kontingent innerhalb des Zeitfensters. |
| x-ratelimit-remaining | Was in diesem Zeitfenster noch übrig ist. |
| x-ratelimit-reset | Sekunden bis zur Erneuerung des Kontingents. |
| retry-after | Wie viele Sekunden bis zum nächsten Versuch. Nur in der Antwort vorhanden, welche die Anfrage abgewiesen hat. |
Ist das Limit überschritten, wird die Anfrage abgewiesen, und die Antwort nennt die Wartezeit in Sekunden. Ein erneuter Versuch erfolgt nach dieser Zeit, nicht sofort.
Fehlerformat
Jeder Fehler kommt im selben Umschlag zurück: ein kurzes Codefeld, nach dem die Maschine verzweigt, und ein Erläuterungsfeld, das ein Mensch liest.
- errorDer kurze Code, nach dem der Client verzweigt.
- messageDie Erläuterung dessen, was geschehen ist.
| Status | Codefeld | Bedeutung |
|---|---|---|
| 400 | Bad Request | Die Anfrage entspricht nicht dem Schema. Die Erläuterung benennt das fehlende oder ungültige Feld. |
| 401 | unauthenticated | Es liegt keine gültige Identität vor: Es wurde kein Token gesendet, es ist abgelaufen oder es ließ sich nicht verifizieren. |
| 404 | Not Found | Diesen Endpunkt gibt es nicht, oder es gibt keinen solchen Datensatz. |
| 429 | Too Many Requests | Das Ratenlimit wurde überschritten; die Antwort nennt die Wartezeit. |
| 5xx | internal_error | Ein unerwarteter Fehler. Das Detail wird nicht an den Client gegeben, sondern in das Serverprotokoll geschrieben. |
Seitenaufteilung
Endpunkte, die Listen zurückgeben, nehmen dieselben zwei Parameter entgegen und liefern dieselben Zähler, sodass ein blätternder Client nicht für jeden Endpunkt neu geschrieben wird.
- limitWie viele Datensätze eine Seite fassen soll. Mindestens einer, höchstens zweihundert; ohne Angabe fünfzig.
- offsetWie viele Datensätze übersprungen werden. Beginnt bei null.
- totalWie viele Datensätze insgesamt auf die Filter passen.
- countWie viele Datensätze diese Antwort tatsächlich enthält.
Die Antwort gibt außerdem das verwendete limit und offset zurück; der Client liest seine Position aus der Antwort, statt sie zu erraten.
Datenaustausch und Webhooks
Der Austauschmodus ist eine Einstellung, kein eigenes Produkt: Jede registrierte Anwendung trägt den Modus, in dem sie arbeitet, in ihrem eigenen Datensatz.
| Modus | Bedeutung |
|---|---|
| Einseitig – ausgehend | Optifora veröffentlicht Daten; die Gegenseite liest sie oder abonniert Ereignisse. |
| Einseitig – eingehend | Die Gegenseite schiebt Daten hinein; Optifora prüft sie und schreibt sie fort. |
| Beidseitig | Beide Seiten schreiben; die Konfliktregel ist vorab festgelegt. |
| Handshake | Jede Übertragung eröffnet eine Sitzung: Angebot, Prüfung, Freigabe, Übertragung und Quittung. Die Quittung bleibt bei beiden Seiten. |
- Ereignisse werden hinausgeschobenEin Webhook sendet das Ereignis an die Rückrufadresse, welche die registrierte Anwendung hinterlegt hat. Ein Ereignis, das nicht zugestellt werden kann, bleibt in der Warteschlange und wird erneut versucht; es geht niemals stillschweigend verloren.
- Dieselbe Anfrage schreibt nicht zweimalEine schreibende Anfrage führt einen Idempotenzschlüssel mit. Eine zweite Anfrage mit demselben Schlüssel legt keinen zweiten Datensatz an.
- Jeder Aufruf wird gemessenWer wann mit welchem Umfang und mit welchem Ergebnis aufgerufen hat – all das wird festgehalten. Derselbe Datensatz beantwortet sowohl die Fehlersuche als auch die Frage, wer diese Daten abgerufen hat.
- Unsere eigenen Anwendungen nutzen dieselbe TürEinen privilegierten zweiten Weg gibt es nicht. Unsere eigene Integration ist der Beweis für die Oberfläche, die ein externer Entwickler vorfindet.
Das Datenmodell für die Austauschschicht steht; die zugehörigen Endpunkte sind noch nicht veröffentlicht. Sobald sie es sind, verweist dieser Abschnitt auf ihre Einträge in der Referenz.
Referenzdokumente
Die Referenz wird nicht von Hand geschrieben, sondern aus den Schemata der Endpunkte erzeugt. Sobald ein Endpunkt sein Schema übergibt, füllt sich das Dokument von selbst, sodass Dokument und Verhalten nicht auseinanderlaufen können.
- Heute: in VorbereitungDie Schemata rücken Modul für Modul nach. Bevor das Dokument veröffentlicht wird, sind darin Anfrage und Antwort jedes Endpunkts sichtbar.
- Zwei Formate werden veröffentlichtEin maschinenlesbares OpenAPI-Dokument und eine Referenzseite, die aus demselben Dokument erzeugt und im Browser durchblättert wird.
- Der Zugriff ist gestuftDie Übersicht steht allen offen. Die vollständige Referenz kann hinter einem Dokumentationstoken liegen, das einem registrierten Integrator ausgestellt wird; Produktionsschlüssel und Rückrufadressen sind ohnehin keine Sache der Dokumentation – sie gehören zum Datensatz der Anwendung.
- AdressstandardZwei Referenzen werden veröffentlicht, ihre Adressen stehen fest: client-api.optifora.com/docs ist offen, admin-api.optifora.com/docs verlangt eine Berechtigung und ist nach außen geschlossen. Beide sind heute noch nicht aktiv; die Links werden in diesem Abschnitt ergänzt, sobald sie es sind.
Wenn Ihr Integrationsvorhaben bereits feststeht, schreiben Sie uns über die Kontaktseite: Sie erfahren als Erste, wenn die Oberfläche geöffnet wird.
Haben Sie ein konkretes Anliegen?
Diese Seiten erklären, wie der Supportablauf funktioniert. Wenn Sie ein Anliegen oder eine Frage haben, schreiben Sie uns über die Kontaktseite.
Zur Kontaktseite