Braze OpenAPI仕様の使用
このリファレンス記事では、BrazeがREST APIエンドポイントのOpenAPI仕様を公開する方法と、それらの仕様に含まれるスキーマを活用して開発ワークフローを効率化する方法について説明します。
各Braze REST APIエンドポイントページでは、OpenAPI仕様から生成されたインタラクティブなリファレンスが表示されます。このリファレンスには、エンドポイントのパラメーター、リクエストボディ、レスポンススキーマ、レスポンスの例が一貫した構造化されたフォーマットで表示されます。各仕様は機械可読なファイルでもあり、ダウンロードしてご自身のツールで直接使用できます。
各エンドポイントページのリファレンスは読み取り専用です。ドキュメントサイトからライブリクエストを送信することはできません。エンドポイントを呼び出すには、生成されたcURLの例をコピーするか、スキーマの使用方法の説明に従って、ダウンロードした仕様をご自身のクライアントで使用してください。
仕様の入手先
任意のREST APIエンドポイントページで、エンドポイントリファレンスセクションを見つけてください。生の仕様を開くには、そのセクションの仕様ダウンロードオプションを使用します。各ファイルは、以下のフォーマットの安定したパブリック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スキーマバリデーター、またはお使いの言語のライブラリーを使用して、ペイロードをスキーマに照らして検証します。
- バリデーターが欠落、型不一致、範囲外としてフラグを立てたフィールドを修正します。
Postmanまたは他のクライアントへのインポート
事前入力されたリクエストとインラインのフィールド説明を取得するには：
- PostmanでImportを選択し、ダウンロードした仕様ファイルを選択します。
- Postmanがエンドポイント、パラメーター、サンプル値を含むコレクションを作成します。
- REST APIキーとターゲットのRESTエンドポイントを追加し、リクエストを送信します。
エンドポイントのモック
ライブインテグレーションコードを書く前にエンドポイントに対してビルドするには：
- Prismなどのモックツールに仕様を読み込みます。
- モックサーバーを起動すると、仕様のスキーマに一致するレスポンスが返されます。
- 開発中はアプリケーションをモックサーバーに向け、準備ができたらライブのRESTエンドポイントに切り替えます。