用于资源修改的 REST API 设计：捕获所有 POST 与多个端点答案

【问题标题】：REST API design for resource modification: catch all POST vs multiple endpoints用于资源修改的 REST API 设计：捕获所有 POST 与多个端点
【发布时间】：2019-04-29 16:45:25
【问题描述】：

我正在尝试找出 API 设计的最佳或常见做法。我的担心基本上是这样的：

PUT /users/:id

在我看来，这个端点可以用于多种功能。我会用它来更改用户名或个人资料，但是例如重置密码呢？

从“模型”的角度来看，这可能是标志，是用户的属性，因此发送修改会“起作用”。

但我会期待更多类似的东西

POST /users/:id/reset_password

但这意味着几乎每次修改我都可以根据修改的含义创建不同的端点，即

POST /users/:id/enable
POST /users/:id/birthday
...

甚至

GET /user/:id/birthday

比较简单

GET /users/:id

所以基本上我不明白何时停止使用单个 POST/GET 并创建不同的端点。

在我看来这是一个简单的选择问题，我只是想知道是否有一些标准的方法或一些指导方针。阅读并查看示例后，我仍然不确定。

【问题讨论】：

如果您设计 REST 架构，最好将其视为针对机器而非人类读者的网站。由于 REST 只是通用 Web 的概括，因此同样的概念也适用于它。服务器应该告诉客户端请求应该是什么样子（具有类似于 Web 表单的表示），并允许客户端通过遵循 URI 和“单击”按钮或表单元素来采取进一步的“操作”。如果你想允许修改一个实体的单个元素，使用PATCH，如果你更新整个实体使用PUT，如果不符合上述条件，使用POST

标签： rest

【解决方案1】：

免责声明：在很多情况下，当人们真正想要是具有漂亮 URL 的符合 HTTP 的 RPC 设计时，他们会询问 REST。接下来，我将回答有关 REST 的问题。

在我看来，这个端点可以用于多种功能。我会用它来更改用户名或个人资料，但是例如，重置密码呢？

当然，为什么不呢？

我不明白何时停止使用单个 POST/GET 并改为创建不同的端点。

一个非常好的起点是 Jim Webber 的演讲 Domain Driven Design for RESTful systems。

第一个关键思想 - 你的资源不是你的域模型实体。您的 REST API 实际上是您的域模型前面的一个门面，它支持您只是一个网站的错觉。

因此，您的资源类似于代表信息的文档。 URI 标识文档。

第二个关键思想——客户端使用 URI 来缓存资源的表示，这样我们就不需要一直将请求发送回服务器。取而代之的是，我们在 HTTP 中内置了一组标准的communicating caching meta data 从服务器到客户端的方式。

对此至关重要的是the rule for cache invalidation：成功的不安全请求会使先前缓存的相同资源（即相同的 URI）表示无效。

所以一般规则是，如果客户端要修改他们已经缓存的资源，那么我们希望修改请求转到同一个 URI。

您的 REST API 是使您的域模型看起来像一个网站的外观。因此，如果我们考虑如何构建一个网站来做同样的事情，它可以让我们深入了解我们如何安排资源。

所以借用你的例子，我们可能有一个用户的网页表示。如果我们要允许客户端修改该页面，那么我们可能会考虑一堆用例（启用、更改生日、更改名称、重置密码）。对于每个受支持的案例，我们都会有一个指向特定任务表单的链接。这些表单中的每一个都有允许客户端描述更改的字段，以及表单操作中的 url 来决定表单的提交位置。

由于客户端试图实现的是修改个人资料页面本身，我们将让这些表单中的每一个提交返回个人资料页面 URI，以便客户端知道使如果请求成功，则先前缓存的表示。

因此您的资源标识符可能如下所示：

/users/:id 

/users/:id/forms/enable
/users/:id/forms/changeName
/users/:id/forms/changeBirthday
/users/:id/forms/resetPassword

每个表单将其信息提交给/users/:id。

这确实意味着，在您的实现中，您可能最终会将许多不同的请求路由到同一个处理程序，因此您可能需要在那里消除它们的歧义。

【讨论】：