Braze OpenAPI仕様の使用
このリファレンス記事では、BrazeがREST APIエンドポイントのOpenAPI仕様を公開する方法と、それらの仕様に含まれるスキーマを活用して開発ワークフローを効率化する方法について説明します。
各Braze REST APIエンドポイントページでは、OpenAPI仕様から生成されたインタラクティブなリファレンスが表示されます。このリファレンスには、エンドポイントのパラメーター、リクエストボディ、レスポンススキーマ、レスポンスの例が一貫した構造化されたフォーマットで表示されます。各仕様は機械可読なファイルでもあり、ダウンロードしてご自身のツールで直接使用できます。
各エンドポイントページのリファレンスは読み取り専用です。ドキュメントサイトからライブリクエストを送信することはできません。エンドポイントを呼び出すには、生成されたcURLの例をコピーするか、スキーマの使用方法の説明に従って、ダウンロードした仕様をご自身のクライアントで使用してください。
仕様を確認する場所
任意のREST APIエンドポイントページで、Endpoint reference セクションを探してください。未加工の仕様を開くには、そのセクションの仕様ダウンロードオプションを使用します。各ファイルは、以下の形式の安定したパブリックURLに配置されています。
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
各ファイルは、1つのエンドポイントに対応する単一の自己完結型OpenAPI 3ドキュメントです。ドキュメントには、エンドポイントが受け付けるデータと返すデータの正確な構造を記述するリクエストスキーマとレスポンススキーマが含まれています。
スキーマが有用な理由
スキーマはエンドポイントの構造化された契約です。各フィールドの名前、データ型、フィールドが必須かどうか、許容される値、およびオブジェクトのネスト構造を定義します。この契約は機械可読であるため、リクエストやレスポンスの形式を手動でコピーする代わりにスキーマに頼ることができます。多くのエンドポイントで共有される再利用可能なオブジェクトとフィルターについては、オブジェクトとフィルターを参照してください。スキーマは以下のことに役立ちます。
- クライアントコードとSDKの生成。 好みの言語で型付きのリクエストモデルやレスポンスモデル、または完全なクライアントライブラリを生成することで、リクエストボディを手書きする必要がなくなります。
- リクエストとレスポンスの検証。 送信前にペイロードをスキーマに対してチェックし、レスポンスが期待通りであることを確認することで、インテグレーションのバグを早期に発見できます。
- APIのモック。 スペックからモックサーバーを立ち上げることで、ライブのインテグレーションコードを書く前にBrazeエンドポイントに対してビルドやテストを行えます。
- APIクライアントへのインポート。 PostmanやInsomniaなどのツールにスペックを読み込むことで、事前入力されたリクエスト、パラメータの説明、オートコンプリートを利用できます。
- インテグレーションの同期維持。 スペックの保存コピーを現在のバージョンと比較することで、フィールドの追加や変更を検出し、自信を持ってインテグレーションを更新できます。
スキーマの使用方法
以下の手順は、エンドポイントページからスペックファイルをダウンロード済みであることを前提としています。
スペックの表示と確認
スペックを構造化されたインタラクティブなビューで確認するには、任意のOpenAPIビューアーを使用します。
- 目的のエンドポイントのスペックファイルをダウンロードします。
- Swagger Editor または同様のビューアーを開きます。
- ファイルを貼り付けるかアップロードして、オペレーション、パラメーター、および定義されているすべてのスキーマを確認します。
クライアントまたはモデルの生成
スキーマをお使いの言語の型付きコードに変換するには、OpenAPIジェネレーターを使用します。
- OpenAPI Generator などのジェネレーターをインストールします。
- ジェネレーターにスペックファイルを指定し、ターゲット言語を選択します。
- 生成されたリクエストモデルとレスポンスモデル、または完全なクライアントをアプリケーションで使用して、リクエストボディを手動で構築する手間を省きます。
ペイロードの検証
リクエストボディを送信する前に、エンドポイントの仕様に一致していることを確認するには、以下の手順を実行します。
- スペックからリクエストボディスキーマを抽出します。
- JSON Schemaバリデーター、またはお使いの言語のライブラリを使用して、スキーマに対してペイロードを検証します。
- バリデーターが不足、型の不一致、または範囲外としてフラグを立てたフィールドを修正します。
Postmanまたは他のクライアントへのインポート
事前入力されたリクエストとインラインのフィールド説明を取得するには、以下の手順を実行します。
- PostmanでImportを選択し、ダウンロードしたスペックファイルを選択します。
- Postmanがエンドポイント、パラメーター、およびサンプル値を含むコレクションを作成します。
- REST APIキーとターゲットのRESTエンドポイントを追加して、リクエストを送信します。
エンドポイントのモック
ライブの統合コードを記述する前にエンドポイントに対して開発を行うには、以下の手順を実行します。
- Prism などのモックツールにスペックを読み込みます。
- モックサーバーを起動します。スペックのスキーマに一致するレスポンスが返されます。
- 開発中はアプリケーションをモックサーバーに向け、準備ができたらライブのRESTエンドポイントに切り替えます。