API エンドポイントドキュメントガイドライン

一般的に、API エンドポイントのドキュメントは一般ガイドラインに従う必要があります。ただし、このドキュメントに記載されている特定のトピックについては、異なるコンテンツガイドラインが必要になる場合があります。

Braze は以下の REST API メソッドをサポートしています：

• GET
• DELETE
• PATCH
• POST
• PUT

新しいエンドポイント記事の作成

新しいエンドポイント記事を作成する際は、そのエンドポイントを Braze API ガイドにも追加して、検索可能にしてください。_docs フォルダ > _api フォルダ > home.md ファイルに移動し、エンドポイントのパスと1文の説明を追加します。

エンドポイントの参照方法

一般的に、ドキュメントでエンドポイントを参照する際の明確な規則はありません。Braze のエンドポイントを参照する場合は、ユースケースに応じてエンドポイントの参照方法を判断してください。

エンドポイントはパス（例：/users/track）で参照するか、エンドポイント名に「endpoint」という単語を付けて参照できます（例：the track user endpoint）。パスが特に長い場合は、エンドポイント名で参照してください。

エンドポイント名で参照する場合は、文のスタイルを使用します。パスで参照する場合は、コードテキストを使用します。

セクション名を直接参照する場合を除き、「endpoint」という単語を大文字にしないでください。エンドポイントを直接参照する場合は、「API」という単語を含めないでください。

エンドポイントが API として参照される場合もあります。例えば、Braze のエンドポイントについて一般的に述べる場合、「Braze uses a REST API with many endpoints」は正確な表現です。

エンドポイント名を引用符で囲まないでください。パスを参照する際にプレーンテキストを使用しないでください。

エンドポイント記事へのリンク

エンドポイント記事を参照する際は、コンテキストから外れても意味が通じる意味のあるリンクテキストを使用してください。エンドポイントのパスをリンクとして使用する場合は、パスだけではエンドポイントの機能が明確に伝わらない可能性があるため、周囲のテキストで詳細を提供してください。

見出し

エンドポイント記事の導入部には、以下の情報を含める必要があります：

• リクエストタイプとエンドポイントパス URL
• エンドポイントの簡単な説明（「Use this endpoint to…」で始めます）
• 「See me in Postman」リンク
• 必要な REST API キーの権限を示す注意アラート

以下のチェックリストを使用して、各エンドポイント記事に適切な見出し（およびコンテンツ）が記載された順序で含まれていることを確認してください。エンドポイント固有のサブ見出し（異なるタイプのリクエスト例など）がある場合もあります。

• レート制限
• パスパラメーター
• リクエストボディ
• リクエストパラメーター
• リクエスト例
• レスポンスパラメーター
• レスポンス例
• トラブルシューティング（該当する場合）

フォーマットのガイドラインについては、見出しとタイトルを参照してください。

パスパラメーター

エンドポイントにパスパラメーターがある場合は、パスパラメーターの見出しとテーブル（リクエストパラメーターテーブルと同様）を含めてください。

エンドポイントにパスパラメーターがない場合は、パスパラメーターの見出しと次のコールアウトを含めてください：「There are no path parameters for this endpoint.」

エンドポイントにパスパラメーターもリクエストパラメーターもない場合は、以下のように同じセクションに注意書きをまとめてください。

命名規則

各エンドポイント名は、メソッドの後に能動的な動詞で始めてください。これにより、ユーザーはエンドポイントの機能をすぐに理解できます。

エンドポイント名の先頭の動詞として API メソッドを使用しないでください。

この命名規則の例外は、Export セクションのエンドポイントです。セクション名自体が、リストされた情報をエクスポートできることを示す動詞になっているためです。

API キーの権限

API キーの権限は、特定の API コールへのアクセスを制限するためにユーザーまたはグループに割り当てることができる権限です。各エンドポイントのドキュメントでは、Postman ドキュメントリンクの後に以下のコールアウトを含めてください：

To use this endpoint, you must generate an API key with the permission_name_here permission.

API キーの権限の完全なリストを確認するには、Braze ダッシュボードの設定とテストにある設定 > API キーに移動してください。フルアクセスの API キー（キー名には通常「full access」というフレーズが含まれています）を選択します。各権限名は通常、エンドポイント名と一致します。

SCIM エンドポイントには、開発者コンソール外で行われる SCIM インテグレーションに固有のものであるため、API キーの権限がリストされていないことに注意してください。

レート制限

一般的に、レート制限にはリクエスト数と割り当てられた時間を指定する必要があります。

合計レート制限を共有するエンドポイントに注意してください。例えば、すべての非同期カタログアイテムエンドポイントは合計レート制限を共有しているため、それぞれの記事でその旨を示すことが重要です。

レート制限ファイルの更新方法

エンドポイントのドキュメントでレート制限の更新または新しいレート制限のリストが必要な場合は、_docs > _api > api_limits.md に移動してレート制限を編集してください。

パラメーター

リクエストパラメーターとレスポンスパラメーターを2つの別々のテーブルで定義してください。これらのテーブルには以下の列を含める必要があります：

• Parameter
• Required
• Data Type
• Description

エンドポイントのパラメーターを直接参照する場合や、Parameter 列に値をリストする場合は、コードテキストを使用してください。Required、Data Type、Description 列に値をリストする場合は、先頭を大文字にしてください。

プレースホルダーテキスト

プレースホルダーテキストには、ユーザーが含めるべき内容の簡単な説明を波かっこで囲んで使用してください。

API キーのプレースホルダーには、YOUR-REST-API-KEY ではなく YOUR_REST_API_KEY を使用してください。

API キーのプレースホルダーには、YOUR-REST-API-KEY（ハイフン付き）ではなく YOUR_REST_API_KEY（アンダースコア付き）を使用してください。

リクエストとレスポンス

API リクエストには、ヘッダーとリクエストパラメーターが含まれます。リクエストパラメーターは以下のようにフォーマットしてください：

1
parameter": (required/optional, data type) A brief description

以下は、Create new user alias エンドポイントのリクエストボディの例です：

1
2
3
4
5
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
  "user_aliases": (required, array of new user alias object)
}

リクエスト例で文字列または配列のパラメーターを識別するには、二重直線引用符（” “）を使用してください。すべての開きかっこが閉じられていることを確認してください。

API レスポンスには、レスポンスボディ、ヘッダー、および HTTP ステータスコードが含まれます。常にレスポンス例を含めてください。この例には、パラメーターを説明するシンプルなテキスト例を含める必要があります。以下は、Update user alias エンドポイントのレスポンス例です。

1
2
3
4
5
6
7
8
9
10
11
12
curl --location --request POST 'https://rest.iad-01.braze.com/users/alias/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "alias_updates" :[
    {
      "alias_label": "example_alias_label",
      "old_alias_name" : "example_old_alias_name",
      "new_alias_name" : "example_new_alias_name"
    }
  ]
}'

ステータスコードとエラーコード

ステータスコードは、ユーザーの特定のリクエストが正常に完了したかどうかを示します。何が成功とみなされるかをユーザーに知らせるために、ステータスコードを含めると役立ちます。例えば、400 と 404 はエンドポイントのエラーレスポンスの指標となります。

エンドポイントのドキュメントでエラーコードをリストする必要がある場合は、_docs フォルダ > _api フォルダ > errors.md ファイルにある API Error and Responses 記事にリンクしてください。

サンプルコード

サンプルコードは、サンプルリクエストやレスポンスと同様に、最小限の作業でコピーして使用できるようにする必要があります。プレースホルダーテキスト（例：ヘッダー内の API キー）を除き、リクエスト例はそのまま動作する必要があります。Postman を使用して、リクエストが正しくフォーマットされていることを確認してください。

整形コードとミニファイコード

エンドポイントのリクエストにボディが含まれている場合は、Postman で例を整形してください。これにより、Braze の規則を学んでいる開発者がリクエストの各部分を理解しやすくなります。

エンドポイントのリクエストボディが非常に短い場合やボディが含まれていない場合は、不要な空白が削除されるようにリクエストをミニファイしてください。JSON Minifier などのツールを使用してください。

インラインコメント

コード例の単一行コメントを示すには、2つのスラッシュ（//）を使用してください。

インラインコメントは、コードの特定のセクションにユーザーの注意を引いたり、コードブロックの機能を説明したり、追加のコンテキストを提供したりするための有用なツールです。

インラインコメントを使用して、ユーザーのロジックレイヤーが配置される場所と、SDK コードをどのように参照するかを素早く示してください。シンプルで現実的な例を使用してください。例えば、「example_attribute」よりも「favorite_movie」という属性の例の方が効果的です。ユーザーのビジネスがエンドユーザーのお気に入りの映画を追跡していなくても、この例はこの属性を通じて追跡される可能性のある種類のユースケースを示しています。一般的な例では、同じ直感的な理解を引き出すことができません。

人間が読めるコードやメソッド名を単に繰り返すだけのインラインコメントは避けてください。代わりに、Braze 固有のメソッドやパラメーターにさまざまな同義語を使用して、英語を母語としない方への理解の足がかりを提供してください。

一般的に、インラインコメントを提供する際は標準的な英語の規則に従ってください。例えば、文は大文字で始め、単語は完全にスペルアウトしてください。

その他のリソース

• Google developer documentation style guide
  • API reference code and comments