如何为 PUT 和 POST 正确构建 REST 端点

Question

我有一个用于管理用户的 REST 服务。

HTTP GET("/users") - 获取所有用户
HTTP GET("/users/{id}") - 获取特定用户的数据

当更改有关用户的某些内容时，我不确定如何构建 PUT/PATCH 的路径。

选项 1：
HTTP PUT ("/users") 并在请求正文中传输用户数据（id、名字、姓氏）
HTTP PATCH ("/users") 并在请求正文中传输用户的 ID 和 PASSWORD

选项 2：
HTTP PUT ("/users/{id}") 并在请求正文中传输用户数据（id、名字、姓氏）
HTTP PATCH ("/users/{id}") 并在请求正文中传输用户的 ID 和 PASSWORD

选项 3：
HTTP PUT ("/users/{id}") 并在请求正文中传输用户数据（id、名字、姓氏）
HTTP PATCH ("/users/{id}/password") 并在请求正文中传输用户的 ID 和 PASSWORD

@RequestMapping(value = "/users") 公共接口用户控制器 {

@GetMapping(value = "/{id}", produces = "application/json")
User getUser(@PathVariable long id);

@PutMapping(value = "", consumes = "application/json")
void addNewUser(@RequestBody User ser);

@PatchMapping(value = "/{id}/password", consumes = "application/json")
void changeUserPassword(@RequestBody UserPasswordChange passwordChangeModel, @PathVariable String id);

我不确定这些方法中哪种方法最好。我每次都可以从请求正文中获取所有数据，但我不确定创建的最佳路径应该是什么。使用“/users/{id}”更改有关用户的详细信息是有意义的，因为我正在为特定用户进行更改，但由于我可以从请求正文中读取 ID，因此路径变量在这里是多余的。

更改密码时也有同样的困惑。由于我在“/users”下只有一个 Patch 端点，我应该仍然使用“/users/{id}/password”还是应该删除“/password”部分？

Answer 1

当更改用户的某些内容时，我不确定如何构建 PUT/PATCH 的路径。

PUT 和 PATCH 都是文档编辑请求。 “请让你对这个资源的表示看起来像我的一样”。

在理想化的形式中，我会有某种 HTTP 感知文档编辑器。我会 GET 你的资源表示，对我的本地副本进行编辑，然后将我的本地副本的表示发回给你。

完成有用的工作是传递这些文档的副作用。见Jim Webber's talk。

选项 1，我认为我们可以简单地拒绝第一原则。如果/users 标识的资源是用户的集合，那么尝试将其表示替换为单个用户的表示并不是朝着有用方向迈出的一步。从语义上讲，如果您想通过与 /users 资源交互来编辑或插入用户，您可以通过以下方式来实现：(a) 对集合的表示进行编辑，并将整个表示发回 (PUT)，或者通过将差异描述发送回服务器 (PATCH)。

选项 2 有一个更微妙的问题——如果密码是 /users/id 资源表示的一部分，那么密码也应该是 PUT 请求正文的一部分。 PUT 和 PATCH 是将我们的本地资源表示传回服务器的不同方式；我们不应该认为它们拥有关于资源的不同信息。

将密码与其他用户分开是完全合理的。除非密码资源的表示相对于密码本身非常大，否则我希望在大多数情况下使用PUT 而不是PATCH。

所以你建议选项 3 最有意义？

不完全 - 两种资源设计（无论是在一个资源中提供所有信息，还是在两个资源之间分配信息）都很好。您选择一个，然后确保用于更新资源的惯用语是合适的。