RESTFUL（超媒体）API 中的动词

Posted 2023-02-16

【中文标题】RESTFUL（超媒体）API 中的动词

【英文标题】：Verbs in a RESTFUL (hypermedia) API

【发布时间】：2014-11-14 10:18:36

【问题描述】：

我的 API 中开始出现 RPC 样式动词时遇到了一些问题。

我的问题是：可以在 Restful API 中使用“提交”、“SendForApproval”、“接受”和“拒绝”这些动词吗？这是否违反了 Restful 原则？命名这些操作的最佳做​​法是什么？

我们的商业案例： 我有一个命令。它以“预购”状态开始。然后我想打电话来根据我们的业务逻辑验证订单。根据验证结果，然后我将其提交或发送以供批准。审批流程在我们的解决方案外部发生，然后当它通过审批流程时，调用 Api 以将订单标记为已接受或已拒绝。

除了简单地更新状态之外，还有更多事情要做 - 我们将内容发送到打印队列、分离跟踪文档等。

所以我们定义的URI是

https://api.site.com/orders               // A list of orders
https://api.site.com/orders/orderId     // An order
https://api.site.com/orders/orderId/ValidationErrors   // Get a list of validation results
https://api.site.com/orders/orderId/Submit             // Submit the order for processing
https://api.site.com/orders/orderId/SendForApproval    // Send to supervisor
https://api.site.com/orders/orderId/Accept             // Supervisor Accepts the order for processing
https://api.site.com/orders/orderId/Reject             // Supervisor can Reject the order

【参考方案1】：

您必须尽可能避免在 URI 中插入动词。此外，我不同意 user1438038，因为 QueryString 过滤器应该用于搜索目的，而不是指定操作。

我相信有更好的方法来解决这个问题。首先，考虑到您不应该以与业务对象高度相关的方式对 RESTful API 进行建模（假设您使用的是 OO 方法）。此外，请记住，从 REST 角度来看，您公开的所有内容都是资源，而不是具有状态和行为的对象。

我将向您建议一种不同的方法，但我不确定它是否能满足您的系统要求，但也许给您一些想法会很有用。在您的情况下，您可以拥有多个资源，例如 PreOrders、Orders、Supervisor...

https://api.site.com/preorders

GET - Display all pre-orders.
POST - Create a new pre-order.

创建新订单：

https://api.site.com/preorders/1 

POST - approves the pre-order. This action's gonna create a new Order.

显示所有等待批准的订单（由 ID=1 的主管）。

https://api.site.com/supervisors/1/orders

搜索已批准和已取消的订单：

https://api.site.com/supervisors/1/orders?status=canceled
https://api.site.com/supervisors/1/orders?status=approved

取消或批准订单：

https://api.site.com/supervisors/1/orders/1 (DELETE cancels the order)
https://api.site.com/supervisors/1/orders/1 (POST approves the order)

我不确定这是否是解决问题的最佳方法，但我很确定这比在 URI 中使用动词要好。

【参考方案2】：

我没问题，我们使用非常相似的设置来管理订单。

但是，另一种可能性是传递action 参数，例如：

https://api.site.com/orders/orderId/?action=accept
https://api.site.com/orders/orderId/?action=reject
...

REST 的总体思路是拥有资源（如order 或customer）。你想要的是更多的 RPC 语义，但没有对错之分。你的做法是合理的。

【参考方案3】：

在 REST uris 中使用动词不是一个好习惯。

因此，如果您想以任何顺序更改状态，您可以发送 PUT/POST 到 https://api.site.com/orders/orderId，仅更新您想要的业务逻辑值。