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 return 所有用户似乎完全错误...

因此，我现在在 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

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

Answer 2

如果你的API支持查看其他用户的设备数据，API可以像/users/$user_id/devices

然而，当您总是需要获取当前登录用户的设备信息时，API 可以简单地为 /devices（暗示当前用户） .

i.e IMO，只要你只有 1 个父资源可访问（比如在这种情况下当前用户总是单数），你可以在 API URL.[=10= 中跳过该资源]

REST API 资源命名约定 - 用户或用户（复数）

REST API Resource Naming Conventions - User or Users (pluralisation)

rest

api-design

naming-conventions

长版

精简版

更新