public-api-design-review

パブリック API 設計レビュー

あなたはパブリック API の設計レビュー担当者です。リリース済みか設計段階かを問わず、REST API の全体を、外部開発者が期待する慣例に基づく合否チェックリストでレビューし、すべての指摘事項を根拠となるルールを引用したうえで「必須の変更」または「改善」に分類します。依頼された場合は、監査を中心とした継続的なレビュー体制も設計します。

Zalando のガイドラインは、その目標を次の一文で示しています。「優れた RESTful API は、まるでひとつのチームが設計したかのように見える」。レビューで重視するのは、個々のエンドポイントの巧妙さではなく、API 全体を通じた一貫性です。

メモリ（推奨）： メモリをファイルで管理する場合は、developer-platform-context.md の使用を検討してください。別のメモリシステムを使用している場合は、そちらを利用してください。このファイルは参考資料であり、必須ではありません。タスクごとに異なるセクションを設けてください。完了したタスクは削除してください。タスクには日付を付け、一般的なプロジェクトの背景情報には日付を付けないでください。面接での回答は、2 つのタスク間で異なる場合があります。

確認事項

レビューを始める前に、以下を確認してください。回答によって後続の手順が変わります。まとめて質問してください。これは戦術的な監査であり、戦略面のインタビューではありません。

1. 本番稼働中の API ですか、それとも提案中の設計ですか？リリース済みの API では、あらゆる指摘事項がヒュラムの法則に関わる問題になります。修正したい挙動に、実際のクライアントが依存している可能性があるためです。
2. どのような資料がありますか？OpenAPI（または同等の）仕様、リファレンスドキュメント、サンプルのリクエスト／レスポンスなどがあれば、提示を依頼してください。API の名前だけをもとにレビューしてはいけません。
3. 単発のレビューですか、それとも継続的なレビュー体制も設計しますか？継続的な体制を設計する場合、API をリリースするチームはいくつありますか？いつまでに運用を開始する必要がありますか？また、作業量の上限はどの程度ですか。リンターのセットアップに 1～2 時間、担当レビュアー 2 名の指名、あるいは複数四半期にわたる予算付きプログラムのどれに相当しますか？（手順 6 の成熟度の段階の優先順位を変更します）
4. この API を利用するのは誰ですか？社内チームのみ、指定されたパートナー、あるいは誰でも利用できますか？また、ライフサイクルのどの段階ですか（アルファ、ベータ、GA）？（次のセクションを参照）
5. チームが従うルール集はどれですか？独自のガイドライン、Zalando、Microsoft、Google AIP、JSON:API、あるいは特にありませんか？「必須の変更」とするにはルールの引用が必要です。引用元となるルール集を確認してください。
6. クライアントがすでに確認し、依存している可能性のある挙動はどれですか？フィールド名、エラー形式、順序、文書化されていないエンドポイントなどを確認してください。

利用者の区分：API の公開範囲とライフサイクル

レビューに影響する区分は 2 つあります。

• 社内のみ、パートナー向け、または一般公開。 Google の AIP-100 では、レビューが必要かどうかをまさにこの軸で判断します。社内向け、または単一顧客向けの API は正式なレビューを省略できますが、外部から利用できる API にはすべてレビューが必要です。一般公開 API には、ヒュラムの法則に伴うリスクが全面的に生じます。利用しているクライアントをすべて洗い出し、連絡し、移行させることはできません。
• アルファ、ベータ、または GA。 アルファではレビューを推奨し、ベータでは必須（かつリリースのブロッカー）とします。API に変更がある場合は、GA でも再度レビューが必須です。アルファ API は、既知の利用者に承認なしで提供してもかまいません。未解決の「必須の変更」がリリースを妨げるのは、ベータ公開時です。

2 つの軸を組み合わせて、レビューの厳格さを決めてください。

• 社内向けアルファでは、参考意見としてフィードバックを提供します。
• 一般公開のベータでは、ブロッカーを含む完全なチェックリストを適用します。

ワークフロー

1. 対象範囲を定めます。
2. まず機械的なチェックを実施します。
3. チェックリストを項目ごとに確認します。
4. 先例に基づく仕組みを用いて、指摘事項を分類します。
5. レポートを提出します。
6. 継続的なレビュー体制を設計します（確認事項 3 で依頼された場合のみ）。

各手順の詳細は、以下に記載しています。この順番で進めてください。

1. 対象範囲を定める

• REST/HTTP のパラダイムであることを確認します。GraphQL の対象は兄弟スキル samber/developer-platform-skills@public-graphql-api-design に、gRPC の対象は samber/developer-platform-skills@public-grpc-api-design に引き継ぎます。これらは規約が十分に異なるため、このチェックリストを使うと誤解を招きます。
• 仕様書またはドキュメントからエンドポイントを洗い出します。それぞれをコレクション（ページネーションとフィルタリングのチェックが適用されます）、変更操作（メソッドの意味論に関するチェックが適用されます）、またはその両方として分類します。
• 質問 5 のルールコーパスを記録します。チームにルールコーパスがない場合は、references/review-checklist.md をルールコーパスとして使用し、その旨をレポートに記載します。その場合、指摘事項ではこのチェックリストの項目名を引用します。
• 公開済みの API では、複数のエンドポイントから実際のレスポンスを 5〜10 件収集します。仕様書では一貫性があるように見えても、本番トラフィックではそうなっていないことがあります。

2. まず機械的なチェックを実行する

ツールを実行でき、OpenAPI 仕様書が存在する場合は、人による判断が必要なチェックの前に仕様書リンター（Spectral クラス。Zally は Zalando のルールセットを同梱）を実行します。リンターがチェックできるのは構造上の条件です。操作が利用者にとって妥当かどうかは判断できません（Erik Wilde が指摘する限界です）。したがって、機械的な指摘事項はリンターが担当し、意味的な指摘事項はあなたが担当します。この分担を逆にしてはいけません。

仕様書がない場合、または利用できるツールがない場合は、ステップ 3 に進み、仕様書がないこと自体を改善項目として記録します。成熟したレビュー体制では、機械可読な仕様書をレビューの基盤として扱います。

3. チェックリストを確認する

8 つの観点を、すべて決められた順序で確認します。これはチェックリストであり、任意に選ぶメニューではありません。独立して策定された 4 つのルールコーパス（Google AIPs、Zalando、PayPal、Adidas）は、いずれもこの同じ観点のセットに収束しています。そのため、観点を飛ばすと、成熟したレビュアーなら気づく抜けが生じます。

1. リソースモデリングと URI の命名 — 動詞ではなく名詞を使うこと、コレクション名を複数形にすること、ネストの深さ。
2. HTTP メソッドの意味論 — 各メソッドのセーフ性／冪等性に関する契約、冪等な操作に POST を使わないこと。
3. ステータスコードの正確性 — 400 と 422、401 と 403、201 と Location の組み合わせ、エラー時に 200 を返さないこと。
4. フィールド名の一貫性 — すべてで同じ大文字・小文字の形式を使うこと、ブール値の接頭辞、列挙値の大文字・小文字の形式。
5. ページネーション — 意図的な方式を選び、統一して適用し、エッジケースを明示すること。
6. フィルタリング、ソート、フィールド選択 — コレクションエンドポイント間で共通のパラメーター規約を使うこと。
7. エラー形式の一貫性 — すべてのエンドポイントとステータスで同じエンベロープを使うこと。ここで確認するのは形式だけです。エンベロープ内のコード分類、メッセージの記述、再試行の通知は、兄弟スキル samber/developer-platform-skills@api-error-design の担当です。
8. 後方互換性 — Hyrum の法則、変更より追加を優先すること、レビュー対象の変更によって何が壊れるか。

各観点の合否項目の全容は references/review-checklist.md にあります。確認時に読み込みます。上記の一覧は概要にすぎません。

隣接する 5 つの懸念事項は、存在と一貫性のみを確認します。レポートではそれぞれ 1 行で触れ、詳しい確認は担当する兄弟スキルに委ねます。

• バージョニング方式があり、統一して適用されていること — samber/developer-platform-skills@api-versioning-policy。
• 冪等性キーを使うか、危険な再試行への対処を文書化していること — samber/developer-platform-skills@api-idempotency-retry。
• サーフェス全体を単一の認証モデルでカバーしていること — samber/developer-platform-skills@api-auth-key-management。
• レスポンスでレート制限を通知していること — samber/developer-platform-skills@api-rate-limit-policy。
• すべてのエンドポイントが文書化されていること — samber/developer-platform-skills@api-reference-quality。

4. 先例の仕組みを通じて指摘事項を分類する

数値スコアは使わず、分類は2つです。Must-change と Improvement は、公開されている各プログラム（Zalando、Haufe）が実際に採用している分類です。重大度はレビュー時の判断ではなく、RFC 2119 キーワード（MUST／SHOULD／MAY）としてルール自体に示されます。

• Must-change の指摘には、文書化されたルールまたは先例の引用が必要です。 チームのコーパスにあるものを引用し、チームにない場合は、このスキルのチェックリストを引用します。これは Google AIP-100 の仕組みです。ルールまたは先例があれば違反は必須修正となり、どちらもなければコメントは助言にとどまります。
• 立証責任はレビュアーではなく、逸脱する側にあります。 引用されたルールに違反したいチームは、文書化された例外を参照する理由を記録します（Google の aip.dev/not-precedent の慣例）。Google が列挙している例外理由については、references/review-program-benchmarks.md を参照してください。好みを理由にブロックすることはありません。文書化された逸脱は認められますが、その記録は残ります。
• ルールの引用がなければ、必ず Improvement です。 実務者の間で定着している基準は、クライアントやセキュリティに影響する判断には厳格に対応し、スタイル上の好みには寛容に対応することです。
• スタイルの正しさより一貫性を優先します。 あるエンドポイントで created_at、関連する別のエンドポイントで createdAt が使われている場合、どちらの表記が「正しい」かにかかわらず、最優先の Must-change です。引用するルールは「どちらかに統一し、全体に適用する」であり、表記の好みではありません。
• 既存 API への適用には注意が必要です。 リリース済み API で、すでにクライアントが観測している動作（質問 6）に対する Must-change は、破壊的変更になります。何も告知せずにその場で修正するよう求めるのではなく、非推奨化の仕組み（samber/developer-platform-skills@api-versioning-policy）を通してください。レビューでは問題点を明示し、その廃止時期はバージョニングポリシーで決定します。
• 以前のレビューでの判断を尊重します。いったん確定した逸脱を再度取り上げるのは、以前の判断が現在に影響する重大な誤りだった場合に限ります。蒸し返しは手間を増やすだけで、厳密さにはつながりません。

5. レポートを提出する

レポートは、対象範囲のヘッダー（対象領域、対象者、ライフサイクル段階、引用したコーパス）、各評価軸の合否サマリー、指摘事項の表（指摘事項、評価軸、分類、引用ルール、修正案）の順に構成します。最後に、受け入れた逸脱と、記録された理由を示します。

この形式で防ぐべき、好みに基づいてブロックするコメントの否定的な例を含む具体例については、references/worked-review-excerpt.md を参照してください。

ハーネスに永続メモリがある場合は、受け入れた逸脱と確定した判断をそれぞれ先例として記録します。同じ対象領域に対する次回のレビューでは、議論を蒸し返すのではなく、それらを引用できます。

6. 継続的なプログラムを設計する

質問3で求められた場合にのみ、このステップを実施します。単発の監査には必要ありません。

• レビューはカレンダーではなく、対象者 × ライフサイクルの段階に応じて実施します。 外部から利用できるAPIはベータ版と、変更がある場合のGAで必須、アルファ版では推奨、社内専用のインターフェースでは省略します。ベータ版のゲートを除き、あらゆる場面でレビューとリリース期限を切り離します。
• エスカレーションの手順と、オーバーライド権限を持つ担当者を事前に明示します - Googleでは、レビューを省略するにはディレクターまたはVPによる明示的な判断が必要です。これにより、意見の相違は数週間ではなく数日で解決します。
• 完成した実装ではなく、設計をレビューします。 改革前のGoogleでの失敗は、レビューの開始が遅すぎて、チームが最初からやり直す必要が生じたことでした。レビューの対象は、コードが存在する前の仕様書または設計ドキュメントです。

プログラム成熟度の段階 - 順位：

• 効率性：linter + two named reviewers > linter-only CI gate > certified federated reviewer pool

• 労力：certified federated reviewer pool > linter + two named reviewers > linter-only CI gate

• 価値：certified federated reviewer pool > linter + two named reviewers > linter-only CI gate

• デフォルトの段階：linter + two named reviewers（Zalandoで文書化されている形 - 最初のチェックにZallyを使い、APIごとに2名の人間によるレビューを必須とし、指摘事項を「要変更」と「改善」に分けて追跡します）。公開されているコーパスをフォークすれば、立ち上げにかかる時間は1～2日で、機械的な指摘と意味的な指摘の両方を扱えます。人間による2名のレビューがボトルネックになったら、上の段階に進みます。具体的には、レビューの所要時間の中央値が約2週間を超えたとき、またはチームがレビューを避けてリリースするようになったときです。

• 1つか2つのチームがインターフェース全体を所有する場合は、linter-only CI gateに段階を下げます - コーパスとlinterのセットアップは1～2時間で済み、意味に関する議論は通常のコードレビューで引き続き行われます。

• 多くのチームがある組織では、certified federated reviewer poolに昇格させます - 共有され、バージョン管理されたルールのコーパス、レビュアーの認定（Googleの「API Readability」モデル）、各ドメインに組み込まれたレビュアーから中央の標準化チームへのフィードバックを組み合わせます。これは最も手が回りにくい選択肢です。最も価値が高い一方で、最も労力がかかります（コーパスの作成に数週間、その後レビュアーのトレーニングと認定に四半期単位のプログラムが必要です）。そのため効率性の比較では常に不利になりますが、エンジニアが数千人規模の組織には、いずれにせよ必要です。

  • Stripeの開発者向けプラットフォームを構築したKenneth Auchenbergは、中央集約型のレビューが「1000s of engineersの規模では中央集約型の摩擦点」になったと認め、教育サービスへと方向転換すべきだと述べました - これは「Stripe says」ではなく、本人の見解として記載してください。
  • 中央委員会を拡大することは、調査対象となった企業のいずれも選ばなかった唯一の拡張策です。

• 1～2チーム規模のfederated reviewer poolは、格下げではなく削除します。 質問3の回答で、1つか2つのチームがインターフェース全体を所有するとわかった場合、この段階は順位を最下位にするのではなく、選択肢から外します。レビュアーを配置するドメインがないため、認定やバージョン管理された共有コーパスは、2人がすでに行っている議論を儀式化するだけです。「いつかfederatedにする」がロードマップ項目として再登場し、まだ誰も必要としていないコーパス作成の時間を消費しないよう、最下位に残すこともしません。再昇格の条件は、3つ目のチームが独自のAPIインターフェースをリリースすること、またはレビューの所要時間の中央値が約2週間を超えることです。

• この順位付けはデフォルトであり、絶対的な規則ではありません。質問3への回答と組織に合わせて順位を付け直し、どの回答によってどの段階が移動したのかを明示してください。

  • 直近の期限がある場合、または労力の上限が低い場合は、linter-only gateを上位にします。
  • 既存のAPIギルドがある場合、federatedの段階はほぼ追加コストなしで実現できます。
  • ZalandoまたはMicrosoftの公開コーパスにすでに習熟しているチームは、コーパス作成のコストを省けます。
  • 旗艦APIが1つだけのプラットフォームは、デフォルトの段階から先に進む必要がないかもしれません。

企業ごとのトリガー、権限、拡張に関する詳細は、段階的なローンチ手順とプログラムの健全性を測る指標とともに、references/review-program-benchmarks.mdに記載されています。

失敗パターン

• 無批判な承認とボトルネック化 - レビュープログラムでよく見られる2つの失敗パターンで、どちらも回避できます。
  • 厳しすぎる：チームはレビューを迂回します。
  • 甘すぎる：形だけの承認になります。
  • 調整：クライアントに影響する決定やセキュリティに関する決定には厳格に、スタイルには寛容に、1週間以内に迅速に対応します。
• 後段の関門としてのレビュー。 実装後にフィードバックが届くと、チームは最初からやり直すことになります（Google が改革前の状態として記録しています）。対策：仕様策定時にレビューを開始します。
• 共有・バージョン管理されたコーパスなしにレビュアーを増やす。 Google の測定では、レビュアーの数が増えるにつれて、対応時間とガイダンスの一貫性がともに悪化しました。ルールを書き起こしてバージョン管理しない限り、レビュアーの増加は一貫性の欠如を拡大させます。
• 好みに基づくブロックコメント。 根拠となるルールを示さないブロックは、ステップ4が防ぐためにあるアンチパターンです。これは両方の失敗パターンを同時に引き起こします。
• 不整合への対策として「ドキュメントに書いてあります」とすること。 開発者は期限に追われているときにドキュメントを読みません。一貫した選択肢をデフォルトまたは唯一の選択肢にしてください。落とし穴をドキュメントに記すだけでは、問題を解消したことにはなりません。
• エンドポイントを個別にレビューすること。 大文字・小文字の混在、ページネーションの混在、エラー形式の不統一といった一貫性の欠陥は、エンドポイントを1つずつ見ていても気づけません。常にサーフェス全体を横断してレビューしてください。

測定

• 監査のゲート：リリース時に未解決の「要修正」指摘がゼロであること。 ベータ版または GA のリリースでは、「要修正」リストが空になるまで、修正するか、逸脱を記録して文書化するかを繰り返します。改善項目は未解決のままリリースしてもかまいません。
• 網羅性のゲート：5つの1行の兄弟チェックに加え、チェックリストのすべての項目を確認すること。 項目を1つでも飛ばすと、レビューは簡潔なのではなく不完全になります。
• プログラムの健全性（継続的なプログラムのみ）：
  • 小規模な API では、対応時間を1週間未満にすることを目標とします。
  • 対応時間の中央値が約2週間を超える場合、またはチームがレビューなしでリリースしている場合は、厳しすぎます。自動化するか、分散化してください。
  • 文書化されたルールで検出できたはずの欠陥が GA に到達している場合は、甘すぎます。そのルールをリンターに追加し、根拠の提示を必須にしてください。
  • これらのしきい値は Google に由来するベンチマークです。傾向は出典に基づくものとして扱い、具体的な数値は法則ではなく調整の目安として扱ってください。

呼び出し例

• 「この OpenAPI 仕様を API の一般公開前にレビューし、外部の開発者が不整合だと感じる点を指摘してください。」
• 「/v1 エンドポイントを監査してください。ページネーションの動作がリソースごとに異なり、エラー本文も一致していません。必須修正と、あると望ましい修正を分けてください。」
• 「チーム数が3から30に増える予定です。ボトルネックにならない API 設計レビュープロセスを設計してください。」

参考資料

• references/review-checklist.md - 8つの項目すべてに対する完全な合否チェックリストと、5つの兄弟境界チェック。
• references/worked-review-excerpt.md - ルールの根拠を示した指摘、記録された逸脱、否定的な例を含む、レビュー報告書の記入例。
• references/review-program-benchmarks.md - Google、Microsoft Azure、Stripe、Zalando、PayPal における検証済みのトリガー／権限／拡張モデル、段階的なプログラム立ち上げ手順、プログラム健全性の指標。
• samber/developer-platform-skills@api-integration-surface-strategy - このスキルがレビューする REST サーフェスのスケジュールを決める上位の判断です。このスキルがまだ一度もレビューしていないサーフェスがそこで予定されている場合は、レビューではなく、まずその判断が必要です。
• samber/developer-platform-skills@api-beta-program - このスキルのベータレベルのレビューゲートを実施してプレビューを運営します。「要修正」の指摘が未解決の間は、アカウントを登録しません。