ゼロから API を設計するとき、先に何を決めるか
設計段階で一行直すほうが、公開後に項目を一つ変えるよりはるかに安く済みます。まだ誰も依存していないうちに、不確実な部分を潰しておきます。
進め方
要件をエンティティと状態遷移に落とす
要件と主な利用シーンを「要件をデータモデルに落とす」に貼り、コードは書かせません。エンティティ、関連と基数、主要オブジェクトの状態遷移、半年以内に変わりそうな項目、プロダクト担当に確認すべき三点を出させます。エンティティと遷移が、どのリソースを公開し、どの操作を直接出さないかを決めます。
実装前に設計の穴を突く
リソース、パス、リクエストとレスポンスの例、ページネーション、エラーコード案を「API設計の穴を突く」に渡します。実装時に問題になりやすい五点、冗長な項目と不足している項目、後方互換のある直し方、より単純な代替案の有無を出させます。今なら文書を直すだけで済み、呼び出し元ができた後は調整が必要になります。
失敗する経路を書き切る
エラーコードと再試行のルールが固まってきたら、関係するコードを「エラー処理をレビューする」に渡します。見るのは失敗経路だけです。握りつぶされた例外、重要な id が欠けたエラー、安全でない重複書き込み、失敗すべきなのに処理を続ける箇所を確認します。出てきたエラーコードと再試行の意味は API ドキュメントに戻し、呼び出し元が依存できる契約にします。
テストで契約を固定する
実装とテストを「テストの抜けを見つける」に渡します。空のリスト、長すぎる項目、二重送信、権限不足、上流のタイムアウトなど、境界を重点的に補います。各ケースに入力、期待値、抜けやすい理由を書きます。契約テストはステータスコードとレスポンス構造を検証し、内部実装には触れません。
契約が固まってから並行タスクに分ける
最後に確定した契約とチーム人数を「並行開発できるタスクに分解する」に渡します。並行にできない順序制約を先に決め、残りを独立して届けられる単位に切り、依存の向きと衝突しやすい共有ファイルを示させます。フロントエンドは契約に沿ってモックで先に進め、バックエンドの完成を待たなくて構いません。
使うプロンプト
よくある質問
API には最初からバージョン番号を付けるべきですか
置き場所は用意しておきますが、初日から /v2 を切る必要はありません。まずリソース名、エラーコード、ページネーションの約束を安定させます。破壊的変更が避けられないときに、バージョンは最も安い分岐手段になります。想像上の変化に備えて層を増やすと、たいてい経路を二重に保守することになります。
実装前でも AI に設計をレビューさせられますか
できますし、そのほうが直すのは安く済みます。リクエストとレスポンスの例、エラーコード、呼び出し元のシナリオを一緒に渡すと、指摘に根拠が出ます。「ユーザー API を設計して」だけでは一般論しか返りません。
エラーコードは細かく分けるほど良いですか
そうではありません。呼び出し元が区別したいのは、再試行できるか、利用者に見せるべきか、権限の問題か、の三点です。この三つでまとめるほうが、何十ものコードを並べるより正しく使われます。