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

在这件事上显然有不同的意见，下面的答案包含了我的个人观点。最重要的是，这都是非常主观的，并且取决于人们看待某种资源（类型）的方式。

当资源指向整个用户时，为什么要使用user 数据库？

我认为，对于包含多个资源的端点，绝对不要使用单数形式。
但是，有人认为我们应该对所有资源都使用单数形式，主要是出于简单性和统一性的考虑。

为什么当资源仅引用users时经过身份验证的用户？

您会对此有不同的看法，但是共识和最广泛采用的是坚持复数，除了只能包含一个项目的资源（例如，一个仅包含一个头像的用户个人资料）。
另外，由于遵循上述逻辑，users资源使用单数形式没有意义，因此我们不想将单数和复数名称混合使用。

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

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

Answer 2

如果您的API支持查看其他用户的设备数据，则该API可能类似于 / users / $ user_id / devices

相反，当您始终需要获取当前登录用户的设备信息时，API可以简单地为 / devices （隐含当前用户）。

即IMO，只要您只能访问1个父资源（例如，在这种情况下，当前用户总是单数），就可以在API URL中跳过该资源。

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

长版

短版

更新

2 个答案: