简版
对于一些人,包括我在内,构建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
之间犹豫不决 - 我认为两者都有强有力的论据,但非常欢迎其他人对此发表意见...简短版 - 简单地说,请考虑以下两个端点:
// Get all users
GET /users
// Update the authenticated user's device token
PUT /user/device
以上两种方式在我看来都是正确的。但是问题在于,我不可能同时拥有
user
和users
,在我看来只能选其一。困境在于:当资源指整个用户数据库时,为什么要使用
user
?当资源只涉及已认证用户时,为什么要使用users
?我无法理解这个问题... 有人对此有什么想法吗?或者,更好的是,有没有替代我的端点结构的解决方案?
更新
经过深思熟虑,我想出了一种替代方案,但我仍然不确定,因为我不太喜欢使用
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}
PUT /users/device
,因为你应该在资源上声明你正在编辑设备的用户,例如PUT /users/self/device
。现在我在考虑做类似这样的事情/auth/device
,其中auth
代表已认证的用户(单数)。你对此有什么想法? - Ben CareyPUT /users/device
不太合适。PUT /users/id/device
或/auth/device
都更好一些。个人而言,我更喜欢第一个选项,因为我觉得为授权用户单独设置资源名称是不必要的。 - Laurens Deprostauth
,因为这似乎有些过度。但是,使用PUT /users/{id|self}/device
就不太对,因为您无法更新另一个用户的设备。换句话说,端点将始终是/users/self/device
。我想这并不是世界末日,但作为一个完美主义者,这真的很让我恼火,因为它看起来就不对...啊啊啊。你认为呢? - Ben Carey/users/id/device
。这似乎是最符合RESTful的方法。 - Laurens Deprost