エンドポイント設計の良い実践まとめ
WebAPI The Good Parts 第2章をもとに、良いURI設計の原則をわかりやすく整理しました。
API を作る人がつまずきやすいポイントを、実例・悪い例とともにまとめています。
🎯 エンドポイント設計で大事なこと
覚えやすくどんな機能を持つURIなのか一目でわかる
- 短く入力しやすい
- 人間が読んで理解できる
- 大文字小文字が混在していない
- 改造しやすい
- サーバー内部構造に依存しない
- 全体のルールが統一されている
という特徴を持ちます。
ではそれぞれどういうことなのか解説していきます
1. 短く入力しやすい
URIは「人間が読む」ことを前提に設計すべきです。長いURIは往々にして不要な情報が入っていたり意味が重複していたりします
✔ 良い例(検索用のAPI）
http://api.example.com/search
❌ 悪い例
http://api.example.com/service/api/search
- 「api」という言葉が重複
- 「service」という類似した概念を示す言葉も含まれている
2. 人間が読んで理解できる
URIを見れば、それ以外の情報がなくてもそれが何を目的としたものなのかがある程度わかることを意味します
❌ 悪い例
http://api.example.com/sv/api/u
- 「sv」も「u」も意味がわからない
- むやみに省略形を使わない
3. 大文字・小文字の混在は避ける（小文字に統一）
WebAPIは検索エンジンの評価を気にする必要がないため、
「大文字アクセス時に 301 リダイレクト」は必須ではありません。
しかし、
http://api.example.com/Users/100
http://api.example.com/users/100
が別扱いになるのは混乱の元となります。
GitHub・Tumblr など多くのAPIは 大文字混在は 404 を返します。
APIのURIは小文字で統一するようにしましょう
4. 改造しやすい予測可能なURI
エンドポイントを見た瞬間、
- IDを変えれば別リソースが取れそう
- パターンがわかる
と直感できることがとても重要です。
✔ 良い例
http://api.example.com/v1/items/12345
❌ 悪い例（ルールが複雑すぎる）
| ID範囲 | エンドポイント |
|---|---|
| 1〜30000 | http://api.example.com/items/alpha/:id |
| 40001〜50000 | http://api.example.com/items/beta/:id |
| 50001〜70000 | http://api.example.com/items/gamma/:id |
→ クライアント側は 場合分け地獄。
予測可能性は API 利用者の負担を大きく減らします。
5. サーバーのアーキテクチャを URI に含めない
以下のように、実装技術が見えるURIはNGです。
❌ 悪い例
http://api.example.com/cgi-bin/get_user.php?user=100
理由：
- 利用者は実装言語など知る必要がない
- サーバー内部構造が漏れ、攻撃者のヒントになる
6. ルールが統一されていること
同じAPI内で表記ゆれがあると、利用者の混乱につながります。
✔ 良い例
GET http://api.example.com/friends/100
POST http://api.example.com/friends/100/messages
❌ 悪い例
GET http://api.example.com/friends?id=100
POST http://api.example.com/friend/100/message
- 単数/複数が混在
- IDをクエリにしたりパスにしたり、ルールが不統一
✔ 最後に：
どうでしたか？今回は「良いURIの設計とは何か？」という超基本的なことに立ち返って解説してみました。これからも「Web API The Good Parts」を読んで得られた知見やまとめを記事化し共有していきたいと思います。