Postman-Collection und OpenAPI-Dokument

KeenAuth veröffentlicht seinen maschinenlesbaren API-Vertrag als zwei Dateien. Beide werden bei jedem Release aus der öffentlichen Definition der Management-API erzeugt und stimmen daher immer mit der API-Referenz überein. Interne Operationen erscheinen darin nie.

Datei Format Download
Postman-Collection Postman Collection v2.1.0 postman_collection.json
OpenAPI-Dokument OpenAPI 3.1 openapi.json

In Postman importieren

  1. Wählen Sie in Postman Import und wählen Sie die heruntergeladene postman_collection.json.
  2. Öffnen Sie die Collection-Variablen und setzen Sie apiKey auf einen Management-API-Schlüssel. Erstellen Sie einen im Dashboard oder mit der CLI; der Schlüssel wird als Bearer-Token gesendet.
  3. Setzen Sie region auf die Region Ihrer Umgebung (eu ist der Standard). Anfragen gehen an den Host api.{{region}}.keenauth.com, Pfad /v1.
  4. Senden Sie eine Anfrage. Jede POST-Anfrage trägt einen Idempotency-Key-Header, den Postman mit einer neuen GUID füllt, sodass eine wiederholte Anfrage sicher ist.

Anfragen sind in einem Ordner pro API-Tag gruppiert. Pfadparameter wie {{user_id}} sind Collection-Variablen: Setzen Sie sie, bevor Sie eine Anfrage senden, die sie benötigt.

OpenAPI-Dokument verwenden

Das OpenAPI-Dokument dient als Eingabe für die Codegenerierung sowie für API-Gateways, Linter und Mock-Server. Dasselbe Dokument stellt die API selbst unter https://api.eu.keenauth.com/v1/openapi.json bereit.

Vertragsarchiv und SDK-Prüfsummen

Das OpenAPI-Dokument wird außerdem unter einem inhaltsadressierten Archivpfad veröffentlicht. Das Pfadsegment ist der SHA-256-Wert der Dokumentbytes, daher ändert sich die Datei unter einem Archivpfad nie:

Datei Inhalt
/openapi/<sha256>/openapi.json Das Dokument, byte-identisch mit /api/openapi.json dieser Version
/openapi/<sha256>/openapi.json.sha256 Die Prüfsumme im sha256sum-Format
/openapi/index.json Die archivierten Dokumente: sha256, info_version, path; current markiert das neueste

Jedes Server-SDK speichert die Prüfsumme des Dokuments, aus dem es erzeugt wurde:

SDK Wo
Node.js (@keenauth/node) Export OPENAPI_SHA256 und keenauth.openapiSha256 in package.json
Python (keenauth-python) keenauth.OPENAPI_SHA256 und die Projekt-URL OpenAPI document in den Paketmetadaten
Go keenauth.OpenAPISHA256

Um einen Download zu prüfen, führen Sie sha256sum -c openapi.json.sha256 in dem Ordner aus, der beide Dateien enthält. Vergleichen Sie die Prüfsumme mit dem Wert, den Ihr SDK meldet, um zu sehen, gegen welche API-Version das SDK erstellt wurde.