SDK と API クライアント

HTTP クライアントから Oblic API を呼び出します。API は HTTPS と JSON を使用しており、各バージョンの OpenAPI ドキュメントから、ジェネレーターで使用言語の型付きクライアントを生成できます。

OpenAPI ドキュメント

バージョンドキュメント認可方法
v1external-v1.jsonAPI キー(認証)
v2external-v2.jsonOAuth アクセストークン(API v2)
  • 各操作には名前があります(operationId)。sendEmail や listMessages などの名前を、ジェネレーターがメソッドに変換します。
  • v1 ドキュメントにはキーの要件が記載されています。 各操作の x-oblic-scopes は、キーが少なくとも一つ保持する必要があるスコープを列挙し、x-oblic-key-roles はその操作を呼び出せるキーのロールを列挙します。
  • v1 ドキュメントでは各拒否を一度だけ定義しています。 各操作の default レスポンスは、status が error に設定されたエンベロープとエラーを表します。

クライアントの生成

多くのジェネレーターは OpenAPI 3.1 ドキュメントを読み込めます。Java が必要な OpenAPI Generator を使用する例です。

v1 用 TypeScript クライアント

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.oblic.app/openapi/external-v1.json \
  -g typescript-fetch \
  -o ./oblic-client

-g python、-g go、-g java、-g php を指定すると、それぞれの言語のクライアントを生成できます。生成されたクライアントの送信処理を確認してください。ジェネレーターは Idempotency-Key を自動で追加しないため、再試行する可能性がある送信には必ず指定します。

クライアントの使用

  • キーはサーバー上で管理してください。 シークレットストアまたは保護された環境変数から読み込み、ブラウザーやアプリがダウンロードするコードには含めないでください。
  • 再試行では同じ Idempotency-Key を使用し、 拒否レスポンスが待機後の再試行を指示した場合に限って再試行します。エラーを参照してください。
  • 各 webhook の署名を検証してから 内容を信頼してください。Webhooksを参照してください。
このページは役に立ちましたか?