Braze OpenAPI仕様の使用
このリファレンス記事では、BrazeがREST APIエンドポイントのOpenAPI仕様を公開する方法と、それらの仕様に含まれるスキーマを活用して開発ワークフローを効率化する方法について説明します。
各Braze REST APIエンドポイントページでは、OpenAPI仕様から生成されたインタラクティブなリファレンスが表示されます。このリファレンスには、エンドポイントのパラメーター、リクエストボディ、レスポンススキーマ、レスポンスの例が一貫した構造化されたフォーマットで表示されます。各仕様は機械可読なファイルでもあり、ダウンロードしてご自身のツールで直接使用できます。
リファレンスからTest Requestでリクエストを送信できます。Bearer TokenフィールドにREST APIキーを入力し、サーバーリストでご自身のREST エンドポイントを選択してください。リクエストはご自身のワークスペースに対して実行され、実際のデータが変更されるため、テスト用ワークスペースのキーを使用してください。PUT、PATCH、またはDELETEを使用するエンドポイントはドキュメントサイトから送信できないため、Test Requestは表示されません。これらのエンドポイントについては、生成されたcURLの例をコピーするか、スキーマの使用方法の説明に従って、ダウンロードした仕様をご自身のクライアントで使用してください。
仕様の入手場所
任意のREST APIエンドポイントページで、リファレンス内のOpenAPIドキュメントをダウンロードを選択するか、ページ末尾のダウンロードリンクを使用します。各ファイルは、次の形式の安定した公開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 エンドポイントに切り替えます。