Was gebaut ist
Was sich in der Oberfläche tun lässt, soll sich auch über eine Schnittstelle tun lassen, mit denselben Rechten, denselben Prüfungen und demselben Verlauf. Das geplante System baut darum die Oberfläche als einen Nutzer der Schnittstelle und nicht als einen Weg daneben. Diese Seite beschreibt, wie die Schnittstelle gedacht ist.
Im System · FORGE · AXON
- Ein Agent in einer Regelgrenze, davor eine Aufruf, dahinter ein Objekt.
- Heraus kommen ein Nachweis und ein Gegenbeispiel.
Eine Handlung, ein Weg
Begriff · Schema
Ein versionierter Vertrag über Felder, Typen und erlaubte Werte. Die Prüfung muss unbekannte und ungültige Eingaben behandeln.
Eine Handlung ist in der Ontologie als Typ beschrieben, mit Schema, Vorbedingungen, benötigtem Recht und Wirkung. Die Schnittstelle bietet jede Handlung an, die das Recht des Aufrufers zulässt, und die Oberfläche ruft sie auf demselben Weg auf. Es gibt keine Funktion, die nur die Oberfläche kennt.
Auch Agenten benutzen dieselbe Schnittstelle: Ihre Werkzeuge sind Handlungen. Damit gelten für Skripte, Oberflächen und Agenten dieselben Prüfungen, und im Verlauf steht, wer aufgerufen hat.
Beschreibung nach OpenAPI 3.1
Begriff · Ontologie
Die gemeinsame Beschreibung einer Organisation: Objekttypen mit Eigenschaften, Beziehungen, Regeln und Handlungen, als Daten mit Version, Herkunft und Recht.
Die Schnittstelle wird mit OpenAPI 3.1 beschrieben. Pfade, Parameter, Antworten und Sicherheitsschemata stehen in einem Dokument, die Datenschemata in JSON Schema. Das Dokument entsteht aus den Handlungstypen und wird nicht von Hand geschrieben; ändert sich die Ontologie, ändert sich die Beschreibung mit ihrer Version.
Aus der Beschreibung lassen sich Clients erzeugen und Aufrufe gegen sie prüfen. Die Beschreibung selbst ist ein Artefakt mit Version und Prüfwert, damit ein Client erkennt, gegen welchen Stand er gebaut wurde.
Zugang mit OAuth 2.0
Der Zugang folgt OAuth 2.0 (RFC 6749). Dienste melden sich mit dem Client-Credentials-Fluss an, Personen mit dem Autorisierungscode-Fluss und PKCE. Die Geltungsbereiche der Token sind die Handlungen, und die Token sind kurzlebig. Ein Agent im Auftrag einer Person erhält ein getauschtes Token nach RFC 8693. Dauerhafte Schlüssel ohne Ablauf gibt es nicht.
Aufrufe werden je Identität und Mandant begrenzt. Wer die Grenze erreicht, erhält die Antwort 429 mit dem Kopf Retry-After, und seine Wiederholung ist ein neuer Aufruf mit eigenem Verlauf.
Wiederholen, ohne doppelt zu wirken
Schreibende Aufrufe tragen einen Idempotenzschlüssel. Kommt derselbe Schlüssel mit demselben Inhalt noch einmal, liefert das System das erste Ergebnis, statt die Handlung zu wiederholen; derselbe Schlüssel mit anderem Inhalt wird abgewiesen. Der Kopf Idempotency-Key ist als Entwurf der IETF beschrieben.
Gegen gleichzeitige Änderungen schützt die erwartete Version des Objekts, bei HTTP über If-Match mit dem ETag. Hat sich das Objekt geändert, antwortet das System mit 412 (RFC 9110), und der Aufrufer entscheidet neu. Braucht die Handlung eine Freigabe, endet der Aufruf mit 202: angenommen, nicht ausgeführt. Er verweist auf die wartende Freigabe und gibt sich nicht als Erfolg aus.
Fehler und Versionen
Fehler kommen im Format von RFC 9457, Problem Details für HTTP-Schnittstellen, als application/problem+json mit type, title, status, detail und einer Kennung aus der Referenz, etwa APPROVAL_REQUIRED. Die Texte nennen keine Inhalte, die der Aufrufer nicht lesen darf, und keine internen Ablaufspuren.
Die Hauptversion der Schnittstelle steht im Pfad. Erweiterungen, die nichts Bestehendes ändern, kommen ohne neue Hauptversion; was Bestehendes bricht, braucht eine. Eine auslaufende Version wird im Voraus über den Kopf Sunset (RFC 8594) angekündigt.
Schema
POST /v1/handlungen/<handlung>/ausfuehrungen
Authorization: Bearer <token>
Idempotency-Key: <schluessel>
If-Match: "<version-des-objekts>"
Content-Type: application/json
{ "actionType": "<objekttyp>.<operation>.v1", "targetId": "<objekt-kennung>", "input": { } }
200 ausgeführt, Ergebnis der Quelle bestätigt
202 angenommen, wartet auf Freigabe
412 Objekt hat sich geändert
403 Handlung für diese Identität nicht erlaubtGrenze
- Grenze
- Die Schnittstelle ist geplant. Der Prototyp von Freigabe und Protokoll belegt weder eine veröffentlichte Schnittstelle noch Zugang mit OAuth 2.0.
Fragen
- Darf ein Skript mehr als die Oberfläche?
- Nein. Beide rufen dieselben Handlungen mit denselben Prüfungen auf. Ein Skript hat nur die Rechte der Identität, mit der es sich anmeldet.
- Heißt 202, dass eine Handlung gewirkt hat?
- Nein. 202 heißt angenommen. Die Handlung wirkt erst, wenn die Freigabe erteilt und die Quelle bestätigt hat.
Quellen
- OpenAPI Specification 3.1.0OpenAPI Initiative. Beschreibung von HTTP-Schnittstellen.
- RFC 9457: Problem Details for HTTP APIsIETF. Format maschinenlesbarer Fehlerantworten.
- RFC 9110: HTTP SemanticsIETF. Bedingte Anfragen mit If-Match, Antworten 202 und 412.
- RFC 6749: The OAuth 2.0 Authorization FrameworkIETF. Zugang mit Token und Geltungsbereichen.