stripe-inspired-api-design-rules

Stripe を参考にした API 設計のベストプラクティス

業界で最も広く称賛され、模倣されている JSON HTTP API である Stripe API の設計規約をまとめたリファレンスです。8 つのカテゴリにわたる、実践的な 52 のルールを収録しています。誤った決定がすべてのエンドポイント、すべての SDK、すべてのクライアント統合に取り返しのつかない影響を及ぼす度合いに応じて、優先順位を付けています。各ルールでは理由を説明し、誤ったコードと正しいコードを示し、正式な情報源へのリンクを掲載しています。

適用する場面

次のような場面で、このスキルを活用してください。

• 新しい JSON HTTP API、または既存 API の新しいエンドポイントを設計するとき
• エンドポイントを追加・変更する API 設計提案、OpenAPI 仕様、PR をレビューするとき
• API の「誤った」構造がクライアントのバグを引き起こしている統合をデバッグするとき
• 命名の一貫性、エラー形式の統一性、互換性リスクについて API を監査するとき
• API 設計レポートを作成するとき（インスペクターツールが出力する Critical / Warning / Suggestion / Positive のようなもの）
• 2 つの設計のどちらかを選ぶ際に、判断の裏付けとなる信頼できる情報源を探すとき
• API 設計を学び始めるとき — まず身につけるべき標準的なパターンをまとめています

これらのルールは汎用的で、Stripe を模倣する API に限らず、あらゆる JSON HTTP API に適用できます。「API design」「OpenAPI」「endpoint」「schema」「webhook」「idempotency」「pagination」「API versioning」などのキーワードや、YAML／JSON 仕様ファイルのレビューが適用のきっかけになります。

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	リソースのモデリングと識別子	CRITICAL	resource-
2	URL 構造と HTTP セマンティクス	CRITICAL	url-
3	リクエストとレスポンスの形式	HIGH	format-
4	エラーとステータスコード	HIGH	error-
5	冪等性と安全な再試行	HIGH	idem-
6	バージョニングと後方互換性	HIGH	ver-
7	命名、ポリモーフィズム、メタデータ	MEDIUM-HIGH	naming-
8	認証、Webhook、検索	MEDIUM-HIGH	ops-

前のカテゴリほど、誤った選択がより広範囲に影響します。リソースのモデリング（数値 ID、object 判別子なし）での誤りは、今後すべてのエンドポイントに波及します。一方、Webhook イベントの命名での誤りは、修正対象が 1 つのカテゴリに限られます。

クイックリファレンス

1. リソースのモデリングと識別子（CRITICAL）

• resource-prefixed-string-ids — すべてのリソースに接頭辞付き文字列 ID を使用する
• resource-object-discriminator — すべてのリソースに読み取り専用の object 判別子を含める
• resource-opaque-ids — ID は最大 255 文字の不透明な文字列として扱う
• resource-unix-seconds-timestamps — すべての日時に Unix 秒（整数）を使用する
• resource-iso-date-only — 日付のみの値には ISO 8601 の日付文字列を使用する
• resource-birthdate-hash — 生年月日は {day, month, year} のハッシュとして表現する
• resource-integer-minor-units — 金額には最小通貨単位の整数を使用し、浮動小数点数は使用しない
• resource-currency-field-not-name — currency フィールドを同じ場所に配置し、フィールド名に通貨を含めない
• resource-decimal-suffix-strings — 整数で表せない高精度の小数には _decimal 接尾辞付き文字列を使用する

2. URL 構造と HTTP セマンティクス（CRITICAL）

• url-plural-collections — コレクション URL は複数形にし、オブジェクト型は単数形にします
• url-post-for-updates — 更新には POST を使用します（PUT や PATCH ではありません）
• url-action-verbs-as-subpaths — CRUD 以外のアクションは命令形のサブパスで表現します
• url-no-bulk-endpoints — 1 リクエストにつき 1 オブジェクトとし、一括処理用エンドポイントは設けません
• url-version-in-path-and-header — URL パスと Stripe-Version ヘッダーにバージョンを指定します
• url-dedicated-search-endpoint — 複雑なクエリには専用の /search エンドポイントを使用します

3. リクエストとレスポンスの形式（HIGH）

• format-form-encoded-requests — フォームエンコードされたリクエストを受け付け、常に JSON を返します
• format-bracket-notation-nesting — フォームの本文内のネストしたフィールドにはブラケット記法を使用します
• format-list-envelope — リストは {object, url, has_more, data} エンベロープで返します
• format-cursor-pagination — オフセットではなく、カーソル（starting_after／ending_before）でページネーションします
• format-no-total-counts — has_more ブール値を使用し、合計件数は返しません
• format-expand-parameter — expand[] を使用して、関連オブジェクトを 1 回のラウンドトリップで展開します
• format-dot-notation-expansion — ドット記法によるネストした展開を許可します（最大深度 4）

4. エラーとステータスコード（HIGH）

• error-top-level-object — 失敗は必ずトップレベルの error オブジェクトでラップします
• error-four-type-enum — 固定の小規模な type 列挙型を使用し、種類を増やしすぎないようにします
• error-message-mandatory-code-optional — message は必須とし、code は任意で、プログラムによる処理にのみ使用します
• error-lowercase-snake-case-codes — エラーコードには SCREAMING_SNAKE_CASE ではなく、小文字の snake_case を使用します
• error-http-status-mapping — エラーの種類を HTTP ステータスコードに一貫して対応付けます
• error-doc-url-on-every-error — すべてのエラーに doc_url リンクとリクエスト ID を含めます

5. 冪等性と安全な再試行（HIGH）

• idem-key-header — すべての変更リクエストで Idempotency-Key ヘッダーを受け付けます
• idem-scoped-per-account — 冪等性キーはグローバルではなく、アカウントごとにスコープを設定します
• idem-24h-ttl — 冪等性キーを 24 時間保持し、72 時間後に削除します
• idem-fail-on-key-reuse — 異なるパラメーターでキーが再利用された場合は 409 を返します
• idem-recovery-points — 複数ステップの冪等な操作にはリカバリーポイントを使用します

6. バージョン管理と後方互換性（HIGH）

• ver-dated-versions — v1/v2/v3 ではなく、日付形式のバージョン（YYYY-MM-DD）を使用します
• ver-account-pinning — 各アカウントのバージョンは、最初のリクエスト時のものに固定します
• ver-additive-changes — 後方互換性のある変更に該当するものを定義します
• ver-version-change-modules — 破壊的変更はそれぞれバージョン変更モジュールにカプセル化します
• ver-tolerate-unknown — クライアントは不明なフィールド、イベント、列挙値を許容する必要があることを文書化します

7. 命名、多態性、メタデータ（中〜高）

• naming-snake-case-wire-format — すべてのワイヤー識別子には snake_case を使用する
• naming-american-english — アメリカ英語のスペルを使用する（cancelled ではなく canceled）
• naming-simple-unambiguous — 名前はシンプルで曖昧さのないものにし、数字で始めず、専門用語を避ける
• naming-type-discriminator-polymorphism — type フィールドと兄弟オブジェクトで多態型を識別する
• naming-metadata-pattern — 厳格な制限を設けた metadata パススルーを提供する
• naming-boolean-past-tense — ブール値には is_／has_ 接頭辞ではなく、過去形の動詞と平易な形容詞を使う
• naming-enums-over-booleans — 新しいステータス／フラグフィールドでは、ブール値より列挙型を優先する

8. 認証、Webhook、検索（中〜高）

• ops-prefixed-api-keys — API キーにはスコープとモードを示す接頭辞を付ける（sk_live_、pk_test_、rk_）
• ops-https-only-basic-auth — HTTPS のみを必須とし、キーをユーザー名として HTTP Basic 認証を使用する
• ops-on-behalf-of-header — マルチテナントの呼び出しには専用の On-Behalf-Of ヘッダーを使用する
• ops-webhook-event-envelope — Webhook イベントでは固定の {id, object, type, data, created} エンベロープを使用する
• ops-webhook-event-naming — イベントタイプの命名規則 — <resource>.<past_tense_action>
• ops-webhook-signature — HMAC とタイムスタンプの許容時間枠を使用して Webhook 配信に署名する
• ops-webhook-at-least-once-handlers-idempotent — 少なくとも1回の配信を文書化し、ハンドラーでは event.id に基づいて重複を排除する

使用方法

「このフィールドはブール値と列挙型のどちらにすべきか？」といった特定の質問については、該当するルール（naming-enums-over-booleans）を直接参照してください。各ルールには、その理由、コード例、正式な情報源が記載されています。

API 全体のレビューや監査を行う場合は、上から順にカテゴリを確認してください。この順序は Stripe 独自の設計上の優先順位に沿っています。まずリソースのモデル化と URL 構造を適切に整え、次に形式、エラー、冪等性、バージョニングに取り組みます。命名と運用面は変更が最も容易なため、最後に扱います。

構造化された指摘レポート（インスペクターツールが出力するようなレポート）を作成する場合は、ルールをスラッグ（resource-unix-seconds-timestamps、format-no-total-counts）で引用してください。これにより、各指摘を具体的で根拠のある情報源にたどれるようになります。

カテゴリの順序付けの根拠となる影響の連鎖についてはセクションの定義を、新しいルールを追加する場合はルールのテンプレートを参照してください。

参考ファイル

ファイル	説明
references/_sections.md	カテゴリの定義と、設計の波及効果に基づく順序
assets/templates/_template.md	新しいルールを作成するためのテンプレート
metadata.json	バージョンと参考 URL
gotchas.md	ルールの適用時に見つかった失敗しやすい点