API設計の穴を突く
コードを書く前に、設計の穴を見つける
これが私のAPI設計です：［設計を貼り付けてください］。レビュアーの立場で突いてください：1）実装時に問題になりやすい点を5つ挙げる；2）冗長なフィールドはどれか、欠けているためにクライアントが二度目のリクエストを強いられるのはどこか；3）後方互換を保った修正案を示す；4）明らかにもっと単純な代替案があるなら、はっきり指摘する。
使い方
指摘をそのまま返して、設計を擁護させてみましょう。擁護できなかった点から直せばよいのです。
向いている場面
- 外部のクライアントがまだ使っていない、または社内の呼び出し元が 1 つだけのエンドポイントです。変更コストが最も低いタイミングです。
- Web とモバイルが並行して開発に入る前に、契約を固めておきたいとき。
向いていない場面
- すでに公開済みで第三者も使っているなら、まず互換性と段階的な移行を話します。指摘の価値は移行案より低くなります。
- 対立点が業務上の意味（このフィールドは返金に当たるのか）で、エンドポイントの形ではないなら、まずプロダクトに確認します。
例
入力
GET /api/v1/orders?user_id=123
200 {"orders":[{"id":1,"status":"paid","items":[{"sku":"A1","qty":2,"price":1990}]}]}
クライアント：ホーム画面は注文数と直近 3 件だけ、明細は詳細画面で取得する。得られるもの
一覧に items を丸ごと埋め込んでいるため、ホーム画面が 3 件の注文のために全明細を取得してしまう点（payload と N+1 の両方が悪化）を指摘します。カーソルページングと総件数がない点、status が生の文字列で将来の状態追加がクライアントを壊す点も挙げます。一覧は要約を返し、明細は `GET /orders/{id}` に分ける案を示し、既存呼び出しを壊さないよう v1 のフィールドは残します。よくある誤用
- 成功時のレスポンス例だけを貼り、エラーコード、空リスト、ページングの境界を書かないと、実際に壊れる分岐の半分を見落とします。
- 指摘を「書き直しの指示」と受け取り、5 件すべてをそのまま採用して、業務上の制約と衝突する項目を確認しません。
こう変えると効く
- 「3 年後に 10 倍のトラフィックになり、Web とアプリの両方が同じエンドポイントを使うと仮定して」と加えると、ページングとバージョニングの問題が出てきます。
- 「各指摘に、壊れるクライアントコードの具体例を付けて」と頼むと、抽象的な設計論を排除できます。