应用程序服务调用的正确 RESTful URL 约定？答案

【问题标题】：Correct RESTful URL convention for application service calls?应用程序服务调用的正确 RESTful URL 约定？
【发布时间】：2012-03-28 15:34:13
【问题描述】：

我已经看到了大量关于如何为基本 CRUD 操作构建 URL 的示例，但在谈论更多类似命令的操作或应用程序服务调用时却很少看到。

例如，假设在我的应用程序服务中，我有一个类似 RemoveOldOrders(int customerId) 的调用，它会从系统中删除任何具有 2 年历史的 ID 为“customerId”的客户的订单。 URL 在我的 restful 服务上会是什么样子？调用的有效负载是什么样的？我会使用什么 HTTP 方法（POST？）？

我的想法是它会是这样的：

/Customer/1/RemoveOldOrders 作为 POST，正文为空（因为 customerID 来自 url）。

是否有关于此类事情的良好指导方针？

更新：我觉得我需要澄清一下我的问题，而不是关于可能重复的帖子的评论（是的，该帖子本质上是在问同样的事情，但我真的不觉得这个问题得到了很好的回答） .

如果我想对资源执行操作但该操作不适合标准 HTTP 动词怎么办？

另一个例子：我的应用程序连接到 ESB，需要有一种方法来强制将我的资源投影到 ESB 上进行处理？在我当前基于 SOAP 的 Web 服务中，我有一个类似的方法：

ExportCustomer(int customerId)

现在，对于 RESTful 服务，我如何在 uri 中表示此操作？ Brian Kelly 的回答中的选项 1 似乎是最合乎逻辑的，例如：

POST http://someapp/api/customer/1/export

或者会：

POST http://someapi/api/customer/export/1

变得更好？

【问题讨论】：

可能重复的问题：stackoverflow.com/questions/6850187/…

标签： rest

【解决方案1】：

任何时候你想为像“remove”这样的动词建模，你应该考虑DELETE。同样，对于“创建”，请考虑 POST（和/或可能是 PUT），对于“阅读”，请考虑 GET，对于“更新”，请考虑 PUT（或者可能是 PATCH）。

因此，对于您的“删除旧订单”示例，您绝对应该使用DELETE。现在您剩下的唯一挑战是如何识别应该删除的订单。一旦你弄清楚了，URI 方案就会随之而来。

这里有一些选项：

DELETE http://your-api.com/old-orders

这里old-orders的含义和范围将由接收这个请求的服务器来决定。这使客户不必这样做，但无法更改该范围。
GET http://your-api.com/order-query?days-older-than=730

这将返回代表旧约会集的http://your-api.com/order-query-result/{some ID} 的Location URI。然后，您可以简单地对该 URI 发出 DELETE 以一举清除旧记录。
与其强制客户端记住发出这种类型的删除命令，不如提供某种configuration 资源，可以通过您的 API 操作该资源以设置诸如purgeRecordsOlderThanDays=730 之类的字段，然后让服务器以cron-like 的方式自动为您完成。那将是我的首选方法。

【讨论】：

好的，但是如果“动词”不属于“删除”、“创建”、“更新”或常见的 HTTP 操作之一怎么办？我用了一个糟糕的例子。我看到作为对我的 OP 的评论提到的类似帖子将其视为“资源”，但在许多情况下并非如此。如果我的资源仍然是客户，但操作非常迟钝，例如“导出到 ESB”，该怎么办？
那么你应该考虑从给你带来麻烦的动词中创建一个名词，然后采取行动。例如，要对“导出到 ESB”进行建模，您可以拥有一个 ESBExporter 资源，然后您可以将其 POST 用于执行实际导出。

【解决方案2】：

对于导出，您需要删除“导出”动词并将其替换为资源的 ESB 表示：-

GET http://someapp/customer/{id}
响应包含一个导出链接：GET http://someapp/customer/{id}/ESB
进入导出链接会返回 ESB 表示（具有适当的内容类型）

【讨论】：

【解决方案3】：

例如，假设在我的应用程序服务中，我有一个类似的调用 RemoveOldOrders(int customerId) 从对于 ID 为“customerId”的客户，系统已使用 2 年以上。 URL 在我的 restful 服务上会是什么样子？什么会调用的有效载荷是什么样的？我会使用什么 HTTP 方法（POST？）？

RemoveOldOrders(int customerId)
DELETE /oldOrders {customerId: id}
DELETE /customer/{id}/orders?old=true
etc...

您应该阅读有关uniform interface / resource identifiers 和HTTP method specification 的更多信息。

URL 并不重要。重要的是您应该拥有带有资源标识符 (URL) 的资源，并且您必须使用统一（标准）接口来操作它们，例如 HTTP 方法的调用。

【讨论】：