OpenAPIスキーマを使用したリクエストバリデーション
このリファレンス記事では、OpenAPIスキーマとは何か、どのように機能するか、Braze REST APIエンドポイントへのリクエストを送信する前に正しく構造化されていることを確認するための使い方について説明します。
すべてのBraze REST APIエンドポイントページでは、OpenAPI仕様から生成されたインタラクティブなリファレンスが表示されます。各仕様にはスキーマが含まれています。スキーマとは、エンドポイントが受け入れるデータと返すデータを機械可読な形式で正確に記述したものです。このスキーマを使用してリクエストをバリデーションすることで、失敗したAPI呼び出しの結果としてではなく、自分のツール上で構造上のミスを検出できます。
Brazeがこれらの仕様をどのように公開しているか、また仕様がサポートするその他のワークフローの概要については、Braze OpenAPI仕様の使用を参照してください。
OpenAPIスキーマとは
スキーマは、エンドポイントのデータに関するコントラクト（契約）です。OpenAPIドキュメントでは、Schema Objectがエンドポイントで使用される各フィールドを定義します。これには、フィールド名、データ型、必須かどうか、許容される値、およびネストされたオブジェクトや配列の構造が含まれます。
OpenAPIスキーマは、JSONデータの構造を記述するために広く採用されている標準仕様であるJSON Schemaに基づいて構築されています。コントラクトが標準的な機械可読フォーマットで表現されているため、手動でフィールドを確認する代わりに、既成のツールを使ってペイロードをスキーマに対して検証できます。関連する概念について詳しくは、Learn OpenAPIおよびUnderstanding JSON Schemaを参照してください。
スキーマの仕組み
スキーマは、少数の構成要素を使用してデータを記述します。最も一般的なものは以下のとおりです。
- 型。
string、integer、number、boolean、array、objectなど、値のデータ型です。詳細については、Swagger ドキュメントの Data types を参照してください。 - 必須フィールド。 データが有効であるために存在しなければならないプロパティのリストです。
- 制約。 許可される値の
enum、format（例:date-time）、文字列パターン、最小値・最大値など、値の範囲を制限するルールです。 - ネストされた構造。 オブジェクトは他のオブジェクトを含むことができ、配列は保持するアイテムのスキーマを宣言するため、スキーマは深くネストされたペイロードを記述できます。
バリデーターはこれらのルールを読み取り、データと比較します。必須フィールドが欠落している場合、値の型が間違っている場合、または値が許可された範囲外にある場合、バリデーターは具体的な問題をレポートします。JSON Schema specification では、このバリデーション動作が詳細に定義されています。
スキーマが有効なリクエストを定義する仕組み
リクエストボディを受け入れるエンドポイントでは、仕様のリクエストボディスキーマが有効なペイロードの構造を正確に記述しています。多くのBrazeエンドポイントでは、ユーザー識別子、メッセージングオブジェクト、オーディエンスフィルターなど、同じリクエスト構造が再利用されています。これらの共有構造のフィールドごとのリファレンスについては、オブジェクトとフィルターを参照してください。文字列の external_id と整数の points が必須で、points が負の値を取れないリクエストの簡略化されたスキーマを考えてみましょう。
{
"type": "object",
"required": ["external_id", "points"],
"properties": {
"external_id": { "type": "string" },
"points": { "type": "integer", "minimum": 0 }
}
}
このスキーマを満たすペイロードは有効です。
{ "external_id": "user-123", "points": 50 }
以下のペイロードはそれぞれ無効であり、バリデーターがその理由を説明します。
{ "points": 50 }は必須のexternal_idフィールドを省略しています。{ "external_id": "user-123", "points": "50" }はpointsを整数ではなく文字列として送信しています。{ "external_id": "user-123", "points": -5 }はminimum制約に違反する値を送信しています。
スキーマを最初に確認することで、APIを呼び出す前に、どのフィールドを送信すべきか、各値がどの型でなければならないか、どの値が許可されているかを把握できます。
スキーマに対するリクエストの検証
エンドポイントのスキーマに対してペイロードを検証するには:
- 目的のエンドポイントの仕様をダウンロードします。各仕様は
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yamlの形式で、安定したパブリック URL から入手できます。 - 仕様からリクエストボディスキーマを抽出します。
- JSON スキーマバリデーター（JavaScript 向けの Ajv や、各言語向けの JSON Schema tools リストにある別のライブラリなど）を使用して、ペイロードをスキーマに対して検証します。
- バリデーターが不足、型の不一致、範囲外として指摘したフィールドを修正し、リクエストを送信します。
Spectral などのツールで仕様全体のリントと検証を行うこともできます。また、OpenAPI Generator を使って型付きリクエストモデルを生成すれば、コードが最初から有効なペイロードを生成するようになります。これらの仕様を使ったステップごとのワークフローについては、スキーマの使い方を参照してください。
スキーマバリデーションが重要な理由
スキーマに対してリクエストをバリデーションすることで、次のようなメリットがあります。
- エラーを早期に発見できます。 API コールが拒否されてから気付くのではなく、自分の環境内でフィールドの不足や入力ミスを検出できます。
- 失敗するコールを減らせます。 最初から正しい形式のリクエストを送信できるため、リトライやトラブルシューティングの手間が減ります。
- 安心してインテグレーションを構築できます。 リクエスト構造を手動でコピーするのではなく、単一のマシンリーダブルなコントラクトに基づいて作業できます。
- チェックを自動化できます。 テストや CI パイプラインにバリデーションを組み込むことで、コードが変更されてもインテグレーションの正確性を維持できます。