当从具有超媒体约束的 REST API 提供响应时，如何向客户端指示要使用哪个 HTTP 方法（动词）？

Question

我认为我已经很好地掌握了 RESTful 架构的原则，但我还没有做到这一点。

我似乎无法弄清楚的是，客户端如何知道每个资源可以使用哪些 HTTP 方法？当应用程序流程中需要执行特定操作才能继续流程时该怎么办？

简化示例：

假设客户向我的 REST API 下了一个简单的订单。

客户端将向以下位置发出发布请求：http://api.mycompany.com/orders

请求负载

<order>
    <items>
        <sku>12345</sku>
        <quantity>1</quantity>
    </items>
</order>

假设请求成功

响应负载

<order>
    <id>156</id>
    <status>Pending Payment</status>
    <items>
        <sku>12345</sku>
        <quantity>1</quantity>
    </items>    
    <links>
        <link rel="order" url="http://api.mycompany.com/orders/156" />
        <link rel="invoice" url="http://api.mycompany.com/payments/156" />
        <link rel="payment" url="http://api.mycompany.com/invoices/156" />
    </links>
</order>

如果我正确理解超媒体约束，我提供相应的资源，客户端可以选择从那里去哪里。

在上面的示例中，带有 rel="order" 的链接可以是 GET、PUT 或 DELETE 请求。带有 rel="invoice" 的链接仅限于 GET 请求。带有 rel=" payment" 的链接将只接受POST请求。

客户怎么知道这一点？我知道如果他们向上述资源之一发出OPTIONS请求，它应该为他们提供可用的方法，但我不确定这是否是处理这种情况的标准方法。

任何帮助将不胜感激。

Answer 1

简单的事实是，这些动词将记录在资源文档中。

您没有问的问题是，“客户如何知道参考‘订单’、‘发票’和‘付款’的用途？”。

然而，他们也面临着你所问的同样的问题。它们也需要记录下来。

当这些被记录下来，当这些关系被解释为它们是什么，它们为什么存在，以及你作为资源消费者将使用它们做什么时，那么利用这些资源所需的实际动词也将与它们一起记录下来。

Answer 2

客户端可以调用您公开的任何 URI 上的任何 HTTP 动词。这些行动是否会产生任何效果是一个单独的问题。

客户端可以以不同的方式发现哪些方法适用于特定的 URI：

1. 它们使用不同的操作调用每个 URI，并动态地找出哪些方法有效（返回 2xx 响应代码）以及哪些方法返回 405 - 不允许的方法< /代码>。
2. 客户端程序员会阅读您的文档并提前对交互进行编码。

老实说，我从未见过在生产系统中实现#1。 #2 对我和大多数必须编写使用 REST API 的客户端的人来说最有意义。

请注意，使用 REST API 不仅仅需要知道要使用哪个 HTTP 动词。媒体类型的内容和结构（对于请求和响应）对于记录并提供给那些计划针对您的系统进行编码的人来说同样重要。