属于经过身份验证的用户的嵌套资源的 REST 路径命名约定是什么？

Question

当经过身份验证的用户希望访问他专有的资源时，在 URL 路径中指定用户 ID 似乎是多余的。

因此，在以下示例中，哪种方式更适合命名我的 API 端点？

示例 1 用户想要更改个人资料图片

PUT /users/{id}/profile-pic 要么 PUT /profile/profile-pic

示例 2 用户想在他的个人资料中添加一个爱好

POST /users/{id}/hobbies 要么 POST /profile/hobbies

Answer 1

很高兴看到人们在 URI 和响应方面关注他们的 API 设计。设计不佳的 API 很快就会消失，因为人们会避免使用它们。

即使它不会公开并且除了你自己或你的团队之外没有人会使用它，想想你的同事和你未来的自己，并花一些时间想想你的 URI 会是什么样子。

回到你的问题我的朋友，根据我邀请你阅读的hands-on restful API design patterns and best practice一书，REST API 由四个独特的原型组成，如 如下：

• 文档：文档是资源表示的基础，具有基于字段和链接的结构。

 https://api-test.​lufthansa.com/​v1/profiles
 https:/​/api-test.lufthansa.​com/​v1/​profiles/​customers

• 集合：集合也是资源，是由 API 提供者或服务器管理的资源目录。

https:/​/api-​test.​lufthansa.​com/​v1/​profiles/​customers/accountbalance
https:/​/api-​test.lufthansa.​com/​v1/​profiles/​customers/memberstatus

• 商店：商店是由客户端管理的资源库。存储允许 API 客户端放入资源，选择要添加的资源的 URI，取出它们，并在决定时删除它们。

http:/​/api.example.com/cart-management/users/{id}/carts
http:/​/api.​example.​com/​song-​management/​users/​{id}/playlists

• 控制器：控制器资源类似于可执行方法，有参数和返回值。 REST API 依赖控制器资源来执行不属于任何 CRUD 方法的特定于应用程序的操作。

POST /alerts/245245/resend

因此，在您的情况下，您可以遵循 GitHub API 的 API 设计。查看组织的how they are retrieving the projects。你的应该是这样的：

PUT /users/{id}/profile-pic
POST /users/{id}/hobbies

对不起，我想把我的观点建立在具体的东西上。

Answer 2

当经过身份验证的用户希望访问他独占的资源时，在 URL 路径中指定用户 ID 似乎是多余的。

不应该；资源标识符的语义和授权头的语义是不同的。

只有 Bob 可以获得/profile/Bob 的副本这一事实是访问策略问题，而不是消息语义问题。

查看菲尔丁对resource 的定义。 “Bob 的个人资料”和“Alice 的个人资料”是不同的可命名信息（假设 Bob 和 Alice 本身是不同的），因此应该有不同的标识符。

这就是“RESTful”的答案。

在实践中，HTTP 有关于身份验证的特殊规则，并且处理经过身份验证的请求意味着您可能会“侥幸”将 Authorization 标头视为资源标识符的一部分（特别是在授权用户仅被允许访问他们自己的资源层次结构的情况下）。