実装が終わってから気づく「API の齟齬」

API 設計レビューを「エンドポイントとパラメータを確認する会議」だと思っていると、バグは素通りする。null 許容やエラー形式のような細部は、レビューの参加者が「実装すれば決まるだろう」と読み飛ばしがちな箇所だからだ。実装が終わってフロントとバックエンドを繋いだ瞬間に、想定していなかった値やエラー形式に当たってやり直しになる——これは設計フェーズで防げるバグである。

この記事では、実装後に発覚しやすい API の齟齬を7項目に整理し、それぞれで実際に起きがちな不具合の型を示す。

レビューで見るべき7項目

1. null 許容とオプショナルの区別

レスポンスの各フィールドが「常に存在するが null になりうる」のか「フィールド自体が存在しないことがある」のかを、フィールドごとに明示する。
起きがちな不具合: フロントが response.user.name を無条件に参照し、退会済みユーザーで user: null が返ってきた瞬間にクラッシュする。

2. エラー形式の統一

エンドポイントごとにエラーレスポンスの形が違うと、フロントは個別対応を強いられる。{ error: string } と { errors: [{ field, message }] } が混在していないか確認する。
起きがちな不具合: バリデーションエラー時だけ配列形式で返るエンドポイントに対し、フロントが文字列前提のエラー表示コンポーネントを使い回し、画面に [object Object] が出る。

3. ページングの方式

offset ベースか cursor ベースかを最初に決める。件数が多い一覧や、書き込みが頻発するデータでは offset だと重複・欠落が起きる。
起きがちな不具合: ページ送り中に新規データが挿入され、offset がずれて同じ行が2回表示される、または1行飛ばされる。

4. 命名規約の一貫性

snake_case と camelCase の混在、created_at と createdAt のどちらを正とするかをレビューで固定する。シリアライザ層で変換するのか、フロントで変換するのかも決める。
起きがちな不具合: 新しいエンドポイントだけ camelCase で返り、既存の型定義を使い回したフロントで値が undefined になる。

5. 冪等性

POST が二重実行されたときにレコードが重複しないか。決済・登録系のエンドポイントは特に重要。
起きがちな不具合: 通信の遅延中にユーザーがボタンを連打し、同じ注文が2件作成される。

6. バージョニングと後方互換性

既存クライアントが動いたまま、フィールドの追加・削除・型変更ができるか。破壊的変更が必要な場合の移行手順まで決める。
起きがちな不具合: 既存フィールドの型を string から number に変更し、旧バージョンのモバイルアプリがパースに失敗して落ちる。

7. 認可チェックの位置

「誰が呼べるか」だけでなく「誰の何を返してよいか」まで確認する。一覧系エンドポイントは特に、自分以外のデータが混ざる事故が起きやすい。
起きがちな不具合: プロジェクト一覧 API が project_id だけで絞り込み、所有者チェックを忘れたため、URL を書き換えると他人のプロジェクトが見える。

レビューの進め方

7項目を毎回フルで議論すると重くなる。実装前に PR や設計ドキュメントの時点で、上記7項目をチェックリスト化して確認欄を作ると流れが速い。

各フィールドの null 許容・optional を明記したか
エラーレスポンスの形式は既存エンドポイントと揃っているか
一覧系はページング方式を決めたか
命名規約は既存の型定義と一致するか
書き込み系エンドポイントは冪等性を検討したか
既存クライアントを壊さない変更か
認可チェックは「本人のデータのみ」まで踏み込んでいるか

Bugoon での実践

この7項目のすり合わせをレビュー会議だけで終わらせると、実装後に気づいた齟齬はまた口頭やチャットで流れて記録に残らない。Bugoon はウィジェットから画面上で不具合を報告できるため、実装後にレビュー漏れが見つかった場合も、該当画面のスクリーンショットと操作ステップを添えてそのまま GitHub Issue に起票できる。フロント・バックエンドどちらの担当が見ても、どのエンドポイントのどんなレスポンスが原因だったかを再現条件つきで残せる。

API設計レビューで潰す7つの穴