Collezione Postman e documento OpenAPI

KeenAuth pubblica il proprio contratto API leggibile dalle macchine in due file. Entrambi sono generati dalla definizione pubblica dell'API di gestione a ogni rilascio, quindi corrispondono sempre al riferimento API. Le operazioni interne non compaiono mai in essi.

File Formato Download
Collezione Postman Postman Collection v2.1.0 postman_collection.json
Documento OpenAPI OpenAPI 3.1 openapi.json

Importare in Postman

  1. In Postman, scegli Import e seleziona il file postman_collection.json scaricato.
  2. Apri le variabili della collezione e imposta apiKey con una chiave dell'API di gestione. Creala nella dashboard o con la CLI; la chiave viene inviata come token Bearer.
  3. Imposta region sulla regione del tuo ambiente (eu è il valore predefinito). Le richieste vanno all'host api.{{region}}.keenauth.com, percorso /v1.
  4. Invia una richiesta. Ogni richiesta POST include un header Idempotency-Key che Postman compila con un nuovo GUID, quindi una richiesta ritentata è sicura.

Le richieste sono raggruppate in una cartella per ogni tag API. I parametri di percorso come {{user_id}} sono variabili della collezione: impostali prima di inviare una richiesta che li richiede.

Usare il documento OpenAPI

Il documento OpenAPI è l'input per la generazione del codice e per API gateway, linter e mock server. Lo stesso documento è servito dall'API stessa all'indirizzo https://api.eu.keenauth.com/v1/openapi.json.

Archivio del contratto e digest degli SDK

Il documento OpenAPI è pubblicato anche in un percorso di archivio indirizzato dal contenuto. Il segmento del percorso è il SHA-256 dei byte del documento, quindi il file in un percorso di archivio non cambia mai:

File Contenuto
/openapi/<sha256>/openapi.json Il documento, identico byte per byte a /api/openapi.json di quella versione
/openapi/<sha256>/openapi.json.sha256 Il digest nel formato sha256sum
/openapi/index.json I documenti archiviati: sha256, info_version, path; current indica l'ultimo

Ogni SDK server registra il digest del documento da cui è stato generato:

SDK Dove
Node.js (@keenauth/node) Export OPENAPI_SHA256 e keenauth.openapiSha256 in package.json
Python (keenauth-python) keenauth.OPENAPI_SHA256 e l'URL di progetto OpenAPI document nei metadati del pacchetto
Go keenauth.OpenAPISHA256

Per verificare un download, esegui sha256sum -c openapi.json.sha256 nella cartella che contiene entrambi i file. Confronta il digest con il valore riportato dal tuo SDK per capire con quale versione dell'API è stato compilato.