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

Posted 2023-03-31

【中文标题】属于经过身份验证的用户的嵌套资源的 REST 路径命名约定是啥？

【英文标题】：What is the REST path naming convention to a nested resource that belongs to the authenticated user?属于经过身份验证的用户的嵌套资源的 REST 路径命名约定是什么？

【发布时间】：2021-09-10 07:00:42

【问题描述】：

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

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

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

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

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

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

【参考方案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

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

【参考方案2】：

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

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

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

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

这就是“RESTful”的答案。

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