RESTful APIで認可情報によって単一リソースを取得する場合の例外的なエンドポイントの命名
お疲れ様です！
GroGroPHPです。
掲題の件、意外と記事になっていなかったので紹介します。
結論
認可トークンやセッションクッキーによって、レスポンスが単一リソースに限られる場合、エンドポイント名は例外的に「/self」とすることができる。
例）users/self
背景
とあるプロジェクトでAPI設計をしていた私。
RESTful APIのベストプラクティスで、エンドポイントは「一貫して複数形を使う」というものがあります。
参考）Zalando RESTful API and Event Guidelines
と言うことで思考停止状態で全てのエンドポイントを複数形にしていました。
しかし、とある英語話者のメンバーから、
「単一のリソースしか返さないのに、複数形になっているのは混乱してしまう」
との指摘を受けました。
それが「users」エンドポイントでした。
調査
うんうん確かにそうだよね…。
リソースは複数取り得るけど、認可情報がヘッダで指定されているから、
実質「users/1」というようなエンドポイントと同等なんだよねぇ…。
説得する材料を探していたところ、先ほどのガイドラインにこんな記述を見つけたのでした。
Exception: the pseudo identifier self used to specify a resource endpoint where the resource identifier is provided by authorization information (see MUST identify resources and sub-resources via path segments).
ちょっと何言ってるか分からないんですが、認可情報使う場合は例外としてselfを使うとのこと。
（英語の問題というより翻訳してもマジで分からん…。）
さらに参照先を見ると↓
Exception: In some situations the resource identifier is not passed as a path segment but via the authorization information, e.g. an authorization token or session cookie. Here, it is reasonable to use self as pseudo-identifier path segment. For instance, you may define /employees/self or /employees/self/personal-details as resource paths — and may additionally define endpoints that support identifier passing in the resource path, like define /employees/{empl-id} or /employees/{empl-id}/personal-details.
はい、さっきよりは分かりやすいです。
selfという擬似識別子を使用することが合理的とのことです。
これでメンバーに説明したところ、一発で理解してくれました！
無事、usersエンドポイントは廃止し、users/selfエンドポイントに変更となったのでした。
まとめ
エンドポイントは一貫して複数形でOK（好みの問題ではありますが、リソースが複数あり、取り得るリソースが複数ある場合、複数形で表現する方が合理的です）
ただし、リソースが複数あるけど、認可情報によって取り得るリソースが単一の場合は、擬似識別子selfを使って合理的にエンドポイントを命名しましょう。