初めてのAPI設計
AIに注意された点
- URLは動詞ではなく名詞で設計する
- ネストは最小限にする
- PUTとPATCHは役割が違う
- 命名規則は統一する
皆さん、こんにちは。私は工学系の学部に所属している学部4年です。
来月から就職先の内定者インターンが始まるため、バックエンドの勉強をしています。
今までAPIの設計をきちんとしたことがなかったので、今回試しにChatGPTに添削してもらいました。
結果 : ボロクソに言われてしまいました！！
ということで、反省の意味も込めてここにまとめておきます！
この記事は2026年4月現在の情報により記述しています。
URLは「リソース（名詞）」で表現する
初めは、/tasks/editのような感じで書いてしまっていました。
フロントばかりやっていたせいもあり、リンクの感覚でエンドポイントを作ってしまっていました...
名詞を使って、操作はHTTPメソッドで表現する方がRESTの考え方に沿っているらしいです。
- PUT /tasks/edit
+ PATCH /tasks/:taskId
ネストが多い
元のエンドポイントは
/projects/:projectId/tasks/:taskId
となっていました。
私の設計でtaskIdによって一意に定まるので、少し冗長です。
- /projects/:projectId/tasks/:taskId
+ /tasks/:taskId
よって、tasks/:taskId とすれば良いことがわかりました。
PUTとPATCHの使い分け
PUTをメインに使っていましたが、PATCHとの違いをあまりわかっていませんでした。
PUT … リソース全体の置き換え（全フィールド更新）
PATCH … 一部のフィールドのみ更新するために使う。
というような違いがあるようです。
PUTはリソース全体の置き換えであり、
POSTのような新規作成とは役割が異なる点に注意が必要とのことです。
| メソッド | 役割 |
|---|---|
| POST | 新規作成 |
| PUT | 全体更新 |
| PATCH | 部分更新 |
URLは camelCaseとsnake_caseのどちらかに合わせる
フレームワークでsnake_caseを使っていたせいで、混ざってしまっていました...
まとめ
今回はインターンが控えていることもあり、ChatGPTに厳しめにチェックしてもらいました。
結果的には学びが多く、おすすめの方法です。
せっかくAIに添削をしてもらえる時代なので、記事を読んで覚えるのも大事ですが、
実際に作って添削させる方が身になる気がしました。
皆さんもぜひ！！
ps.間違いなどありましたら、指摘していただけますと幸いです。
| 項目 | 悪い例 | 良い例 |
|---|---|---|
| URL設計 | /tasks/edit | /tasks/:taskId |
| ネスト | /projects/:id/tasks/:id | /tasks/:taskId |
| 更新方法 | PUTで全部やる | PUTとPATCHを使い分け |
| 命名 | camelとsnake混在 | どちらかに統一 |
参照
- ChatGPT
- 「Webを支える技術」