在REST服务中混合查询和表单参数？

Question

我们有一个REST API，对于某些操作，我们提供异步请求选项。对于异步请求，服务将立即返回一个令牌，该令牌可用于查询完成，而对于同步请求，在操作完成之前不会返回响应。

目前的设计看起来像这样：

网址：PUT /api/orders/1234?async=true

请求正文：customerName=My Company&city=Dallas

直观地说，混合查询和形成这样的参数似乎是错误的，但查询参数（async）是为服务调用提供选项而不是资源的属性。这是我们没有将其包含在请求体中的主要原因。

这种方法看起来是一个好的设计，还是有更好的“REST-y”方法来实现同样的目标？

Answer 1

像这样的网址

POST /api/orders/1234?async=true

不是RESTful。为什么POST？这看起来像RPC over HTTP。

你有什么资源？如果涉及一些计算，则将计算建模为资源。 POST创建一个新的计算集合。收到计算结果的Location标题。

POST /api/orders

custoerName=My Company
city=Dallas

这可能会返回如下响应：

201 Created
Location: /api/orders/1234

然后客户可以GET结果：

GET /api/orders/1234

服务器会响应：

200 OK

Some result body.

如何使这个异步？

你写道：

  

但是查询参数（async）是为服务调用提供选项而不是资源的属性

这是完全错误的。 URI中的 Everything 用于标识资源。 REST不是用参数调用方法。

我建议总是在将计算/交易/购物车建模为资源时使用上述两步法。创建它，检索它。

Answer 2

首选项标题旨在完全按照您的要求进行操作。请参阅spec。