AIにAPIエンドポイント設計を叩かせる｜命名と粒度の詰め方
「この一覧を返すの、/getUserList でいいのかな。それとも /users？」 「1件だけ更新するとき、URLはどう切るのが素直なんだろう」
APIのエンドポイントを切っていると、こういう小さな迷いが次々に出てきますよね。一つひとつは些細でも、決めきれないまま手が止まる。しかも一度クライアントに使われ始めると、後から名前を変えるのは骨が折れる。
そんなとき、AIはエンドポイント設計のたたき台を素早く出してくれる相棒になります。リソースの切り方、パスの命名、メソッドの当て方——設計の初期に「一人では迷っていた観点」をまとめて並べてくれます。
ただ、いきなり「ユーザー管理のAPIを設計して」と聞くと、それらしいけれど、あなたのサービスには少し使いにくい設計が返ってきます。AIは、あなたのクライアントの事情も、既存APIの流儀も知らないからです。
この記事は、AIにREST APIのエンドポイント設計を相談するときの前提の渡し方と、命名・粒度を詰める手順をまとめたものです。長く見えますが、全部は要りません。まず効く所から拾えば回ります。
30–60秒のファストパス（最低ライン）
- 前提を3つ添える：何を操作するリソースか／どのクライアントが使うか／既存APIの命名の流儀を先に伝える（30秒）
- 一発で決めない：「唯一の正解」ではなく「案を2つ、それぞれの向き・不向き付きで」と頼む（10秒）
- 一点だけ確かめる：返ってきたパスが名詞（リソース）中心で、動詞をURLに埋めていないかだけ自分の目で見る（20秒）
※実際のトークンや本番URL・認証情報は貼らない。リソース名と構造だけ渡せば十分。
結論：AIへのエンドポイント設計相談は、「正解を出してもらう」のではなく「前提を渡して、選択肢を一緒に並べてもらう」もの。まず効くのは、①操作するリソース・使うクライアント・既存の命名ルールを先に渡す → ②唯一解でなく「案を2つ＋向き不向き」で出させる → ③パスの命名（名詞中心・複数形・階層）とHTTPメソッドの対応を明示させる → ④粒度（1エンドポイントの守備範囲）が細かすぎ・粗すぎないか聞き返す。AIは設計の視野を広げる相棒であって、あなたのサービスの流儀を保証する人ではありません。
AIに相談するのは、判断を丸投げするためではありません。 一人で命名に悩む時間を減らして、「自分のサービスだとどれが素直か」を落ち着いて選ぶためです。
なぜエンドポイント設計は、AIと相性がよく・同時に危ういのか
AIは、REST APIの定石をよく知っています。「リソースは名詞の複数形で」「取得はGET、作成はPOST」「階層は /親/{id}/子 で表す」——教科書的な観点を、素早く並べてくれます。設計の初期に、抜けていた観点を拾うにはとても向いています。
危ういのは、エンドポイント設計に「唯一の正解」がないことです。使いやすいAPIは、必ずそのサービスの事情に依存します。
- 何を操作するか：扱うリソースの性質で、パスの切り方は変わる
- 誰が使うか：自社の画面だけか、外部にも公開するか、モバイルアプリか
- 既存の流儀があるか：すでにあるAPIの命名やバージョンの付け方に、そろえる必要がある
- これからどう増えるか：後から足したくなる操作、検索や絞り込みの条件
前提を渡さないと、AIはこの空白を「よくあるケース」で勝手に埋めます。だから、それらしいのに自分の現場では扱いにくい設計が返ってくる。逆に言えば、前提さえ渡せば、AIは一気に頼れる相談相手になります。次から、その渡し方です。
相談する前に渡す「4つの前提」
聞き方を変える前に、AIに渡す前提を用意します。ここが揃うだけで、返ってくる案の当たり方が大きく変わります。
①何を操作するリソースか
まず、APIで扱う実体を言葉にします。「会員」「注文」「在庫」——どんなリソースに対して、どんな操作（一覧・取得・作成・更新・削除、それ以外の特別な操作）をしたいのか。操作の一覧を箇条書きで渡すと、AIはパスの構造をつかみやすくなります。
②誰が・何から使うか
APIの設計は「誰が使うか」で変わります。「自社のWeb画面からだけ呼ぶ」「モバイルアプリからも呼ぶ」「外部のパートナーにも公開する」——こうした利用者の広さを渡すと、AIは互換性や公開範囲を意識した現実的な案を出せます。外部公開なら、後方互換をどう守るかも視野に入ります。
③既存APIの命名の流儀
すでに動いているAPIがあるなら、その流儀を渡します。「パスは複数形の名詞」「バージョンは /v1/ で先頭に付ける」「日付はISO形式」——そろえるべきルールを伝えると、AIは既存と浮かない案を返します。ここが抜けると、部分的にきれいでも全体でちぐはぐなAPIになりがちです（→AIにコーディング規約を守らせる指示とチェックの仕込み方）。
④これから何が増えそうか
分かる範囲で、将来の操作も添えます。「後から絞り込み検索を足すかも」「一括更新を入れたくなるかも」。今すぐ作り込む必要はありませんが、伝えておくと、パスやクエリの余地を残した案が返ってきます。
AIにエンドポイント設計を相談する4つの手順
前提が用意できたら、聞き方を工夫します。ここでも「一発で正解を出させない」のがコツです。
手順1：唯一解でなく「案を2つ＋向き不向き」で出させる
いきなり「最適なAPI設計を教えて」と聞くと、AIは1つの案を断定的に返してきます。そうではなく、選択肢を並べてもらいます。
次の前提でREST APIのエンドポイントを設計しています。（①操作するリソースと操作一覧 ②使うクライアント ③既存の命名ルール ④将来の拡張 を貼る）
エンドポイントの設計案を2パターン出して、それぞれについて「向いているケース」と「向かないケース」も添えてください。
こう頼むと、素直にリソース単位で切った案と、画面の都合に寄せてまとめた案、といったトレードオフ込みの比較が出てきます。判断は自分がする、その材料をもらう、という関係にできます（→AIにアーキテクチャ案を出させて鵜呑みにしない比較の型）。
手順2：パスの命名とHTTPメソッドの対応を明示させる
設計案が出たら、ふわっとした説明で終わらせず、一覧表にさせます。
各操作について、HTTPメソッド・パス・意味・想定するステータスコードを表にしてください。パスは名詞中心で、動詞をURLに埋めない方針でお願いします。
ここで名詞中心を指定するのが効きます。REST APIでは、/getUser や /createOrder のように動詞をURLに入れず、GET /users/{id}・POST /orders のように「リソース＋メソッド」で表すのが素直です。表にさせると、命名の揺れ（単数形と複数形が混在、といった細部）にも気づきやすくなります。
手順3：粒度（1エンドポイントの守備範囲）を詰める
命名がそろったら、粒度を確かめます。細かすぎても粗すぎても、後で使いにくくなります。
このエンドポイント群について、粒度が細かすぎる（呼び出しが増えすぎる）箇所と、粗すぎる（1つのエンドポイントが何でも屋になっている）箇所があれば指摘して、まとめ方・分け方の案を出してください。
たとえば、画面表示に毎回3回API呼び出しが要る設計は細かすぎるかもしれない。逆に、1つのエンドポイントに大量のパラメータをぶら下げて何でもこなす設計は、粗すぎて後で読み解けなくなる。AIに両側から見てもらうと、ちょうどいい所を探しやすくなります。
手順4：異常系・境界の扱いを聞き返す
最後に、うまくいかないときの振る舞いを詰めます。ここが設計から抜けると、実装段階で各自バラバラになりがちです。
各エンドポイントで、対象が存在しない・入力が不正・権限がない場合に、それぞれどのステータスコードとエラー形式を返すべきか、方針を統一した形で提案してください。
「見つからないは404、入力不正は400、権限なしは403」といった対応を、API全体で統一しておく。エラーの返し方をそろえておくと、使う側が迷いません。
返ってきた案を鵜呑みにしないために
AIの設計案は、説明が滑らかなほど正しく見えます。でも、滑らかさと、あなたのサービスに合っているかは別の話です。実装に移す前に、この点だけ確かめておくと事故を防げます。
- 動詞をURLに埋めていないか（
/getUsersのような命名が混ざっていないか。操作はメソッドで表すのが素直） - 単数形・複数形や区切りが揺れていないか（
/userと/ordersが混在、snake_caseとcamelCaseが混在していないか） - 既存APIの流儀と浮いていないか（バージョンの付け方、日付や金額の形式が、既にあるAPIとそろっているか）
- 提案の「なぜ」を自分の言葉で説明できるか（この粒度・この命名にした理由を飲み込めるか。分からない所はその場で聞き返す）
全部を採点する必要はありません。自分のサービスと照らして「素直に使えるか」を基準に、合わない所は遠慮なく捨てて構いません（→AIレビューの指摘を取捨選択する判断軸）。
そのまま使えるチェックリスト
- 操作するリソースと操作一覧（一覧・取得・作成・更新・削除など）を渡したか
- 誰が・何から使うAPIか（自社画面・アプリ・外部公開）を伝えたか
- 既存APIの命名・バージョンの流儀を渡したか
- 本番URL・トークン・認証情報を貼らずに、構造だけで相談したか
- 「唯一解」でなく「案を2つ＋向き不向き」で出させたか
- メソッド・パス・意味・ステータスコードを表で明示させたか
- パスが名詞中心で、動詞をURLに埋めていないか確かめたか
- 粒度が細かすぎ・粗すぎないか、両側から指摘させたか
- 存在しない・不正・権限なしの返し方を、API全体で統一させたか
- 提案の「なぜ」を自分の言葉で説明できるか確かめたか
明日やること
いきなりAPI全体を設計し直そうとしなくて大丈夫です。 明日は、いま一番迷っている1リソースだけを選んで、「どんな操作をするか・誰が使うか・既存の命名ルール」の3つをメモにしてからAIに相談してみてください。前提を渡すだけで、返ってくる案の当たり方がまるで変わるのを実感できるはずです。
エンドポイント設計は、一度で完璧な正解を出す仕事ではありません。 前提を渡して、選択肢を並べて、自分のサービスで選ぶ。その積み重ねで、命名の迷いは少しずつ「判断」に変わっていきます。一人で抱え込まなくて大丈夫です。