『Web API: The Good Parts』を参考に、エンドポイント設計について参考になって点を簡単にまとめました。
リソースにアクセスするためのエンドポイント設計で意識すべきこと
1. リソース名は複数形の名詞を使う
APIのエンドポイントは「リソースの集合」を表すため、基本的には複数形の名詞を使います。
例：
GET /users
GET /users/123
「単数形でも良さそう」と思うかもしれませんが、
- データベースのテーブル名が複数形なのと同様、集合体を表現する複数形の方が直感的
- HTTPのURIはリソース（名詞）を、HTTPメソッドは操作（動詞）を表す
この原則を守ることで、API利用者が直感的に理解しやすくなります。
2. 使う単語を慎重に選ぶ
似た意味の単語でもニュアンスが違い、適切な語彙選びが重要です。
例：
- find：探す対象を目的語に
- search：探す「場所」を対象に
APIでは一般的にsearchが使われます。
他にも：
- 場所情報 →
venue - ToDoの項目 →
item - 写真 →
photo（pictureより好まれる）
類似APIや業界標準を調べ、共通の語彙を使うと誤解が減る。
3. 単語を繋ぐ場合はハイフンが無難
単語が複数ある場合の繋ぎ方：
/users/12345/profile-image
/users/12345/profile_image
/users/12345/profileImage
どれでも機能的には問題ありませんが、好まれるのはハイフン（-）。
理由：
- GoogleがSEO的にハイフンを推奨（
_は単語の区切りとみなされない） - URIのホスト名には
_が使えない - 大文字は避ける（小文字統一）
しかし！
最も良いのは単語の組み合わせは極力避けること。
例えば：
/popular-users → /users/popular
のように、単語の組み合わせをパスの階層で表現すると、URIがより構造的かつ視認性の高い設計になります。
以上が『Web API: The Good Parts』を参考にした、エンドポイント設計です。A設計に迷った際の指針にしてください。