Postman コレクションと OpenAPI ドキュメント

KeenAuth は、機械可読な API の仕様を 2 つのファイルとして公開しています。どちらも、リリースごとに公開管理 API の定義から生成されるため、API リファレンスと常に一致します。内部操作はこれらのファイルには含まれません。

ファイル 形式 ダウンロード
Postman コレクション Postman Collection v2.1.0 postman_collection.json
OpenAPI ドキュメント OpenAPI 3.1 openapi.json

Postman にインポートする

  1. Postman で Import を選択し、ダウンロードした postman_collection.json を選択します。
  2. コレクション変数を開き、apiKey に管理 API キーを設定します。キーはダッシュボードまたは CLI で作成できます。キーは Bearer トークンとして送信されます。
  3. region にご利用環境のリージョンを設定します（既定値は eu です）。リクエストは、ホスト api.{{region}}.keenauth.com、パス /v1 に送信されます。
  4. リクエストを送信します。すべての POST リクエストには Idempotency-Key ヘッダーが付与され、Postman が新しい GUID を設定します。そのため、再試行されたリクエストも安全です。

リクエストは、API タグごとに 1 つのフォルダーにまとめられています。{{user_id}} などのパスパラメーターはコレクション変数です。必要なリクエストを送信する前に、値を設定してください。

OpenAPI ドキュメントを使用する

OpenAPI ドキュメントは、コード生成や、API ゲートウェイ、リンター、モックサーバーの入力として使用します。同じドキュメントは、API 自体の https://api.eu.keenauth.com/v1/openapi.json でも提供されています。

仕様のアーカイブと SDK のダイジェスト

OpenAPI ドキュメントは、コンテンツアドレス方式のアーカイブパスでも公開されています。パスのセグメントはドキュメントのバイト列の SHA-256 であるため、アーカイブパスのファイルが変更されることはありません。

ファイル 内容
/openapi/<sha256>/openapi.json ドキュメント。該当バージョンの /api/openapi.json とバイト単位で同一です
/openapi/<sha256>/openapi.json.sha256 sha256sum 形式のダイジェスト
/openapi/index.json アーカイブされたドキュメントの一覧: sha256、info_version、path。最新のものは current で示されます

各サーバー SDK には、生成元となったドキュメントのダイジェストが記録されています。

SDK 記録箇所
Node.js（@keenauth/node） OPENAPI_SHA256 のエクスポートと package.json の keenauth.openapiSha256
Python（keenauth-python） keenauth.OPENAPI_SHA256 と、パッケージメタデータの OpenAPI document プロジェクト URL
Go keenauth.OpenAPISHA256

ダウンロードしたファイルを確認するには、両方のファイルがあるフォルダーで sha256sum -c openapi.json.sha256 を実行します。ダイジェストを SDK が報告する値と比較すると、その SDK がどの API バージョンに対してビルドされたかを確認できます。