REST API 资源命名约定 - 用户或用户(复数)

Question

长版

对于包括我在内的某些人来说，构建 REST API 最痛苦和最头疼的部分之一是确定每个资源的名称和随附的端点。

当然，这取决于个人喜好；社区鼓励某些事情。例如，包括我在内的大多数人都会将他们的资源名称复数化:

GET /notifications
POST /posts

但是，在某些情况下，复数化似乎并不正确。考虑以下示例，其中 user 本质上代表登录用户，而不是整个 users 资源:

端点仅与经过身份验证的用户相关

// Phone Verification
POST /user/phone/request
POST /user/phone/resend
POST /user/phone/verify

// User creation based on authenticated and verified phone
POST /user

// Update authenticated user's profile
PUT /user

// Delete the authenticated user
DELETE /user

// Add/remove the authenticated user's profile image
POST /user/image
DELETE /user/image

// Update the authenticated user's device token
PUT /device/token

访问整个用户资源的端点

GET /user
GET /user/{id|self}

在上面的例子中，对我来说，它感觉像单数 user 资源名称更适合大多数端点，user 指的是经过身份验证的 user，而不是 users 的整个数据库。但是，另一方面，让 GET/user 返回所有用户似乎完全错误......

因此，我现在在 user 和 users 之间左右为难——在我看来，两者都有很强的论点，但非常欢迎其他人对事...

---

精简版

TLDR - 简单来说，考虑以下两个端点:

// Get all users
GET /users

// Update the authenticated user's device token
PUT /user/device

以上两点在我看来都是正确的。上面的问题是我不可能同时拥有 user 和 users，我认为它必须是其中之一。

困境；当资源引用整个用户数据库时，为什么我要使用 user？当资源仅引用经过身份验证的用户时，为什么我要使用 users？

我无法理解这个……有人对此有任何想法吗？或者，更好的是，我提出的端点结构的替代解决方案？

---

更新

经过深思熟虑，我想出了一个替代解决方案，但我仍然不是 100% 确定它，因为我不太热衷于使用 auth 资源名称。

考虑一下:

// auth = authenticated user
// users = users collection

POST /auth/request
POST /auth/resend
POST /auth/verify

POST /auth
PUT /auth
DELETE /auth

POST /auth/image
DELETE /auth/image

PUT /auth/device/token

GET /users
GET /users/{id}

Answer 1

对于这件事显然有不同的看法，下面的回答包含了我个人的看法。归根结底，这一切都非常主观，取决于人们看待特定(类型)资源的方式。

Why would I use user when the resource refers to the entire users database?

在我看来，您永远不应该对包含多个资源的端点使用单数形式。
然而，有些人认为我们应该坚持对所有资源使用单数，主要是为了简单和统一。

Why would I use users when the resource only refers to the authenticated user?

你会发现对此有很多不同的看法，但共识和最广泛采用的通常是坚持复数，除了只能包含一个项目的资源(例如，一个用户个人资料只包含一个头像) .
此外，由于按照上述逻辑对 users 资源使用单数形式没有意义，因此我们不想混合使用单数和复数名称。

// Update the authenticated user's device token
PUT /user/device

您可以按如下方式解释“更新经过身份验证的用户的设备 token ”:
将设备 token 添加到 users 资源集合的 user 实体。