1

我正在处理一个消息请求，该请求将包含用于在目标中创建记录的完整请求详细信息。

这种集成在不同时间创建了 3 种不同类型的记录（订单、装运、发票），即并不总是可以一次创建所有记录，因此我需要让系统知道只创建某些请求。

我的问题，在请求中添加此信息的最佳方式是什么？

  • 它是否需要在请求的正文中？

    {
   "OrderNumber": "1234", 
   "operation": [
     "orderentry",
     "shipment",
     "invoice"
   ]
}

  • 它需要在路径中吗？

     /Order/create?operation=orderentry

  • 它需要在单独的对象中吗？说

     {
   "operation": [
     "orderentry",
     "shipment",
     "invoice"
   ],
   "request": {
     "OrderNumber": "1234", 

   }
}
4

2 回答 2

2

请求的有效 uri 应该标识正在修改的文档；有效载荷应该是描述修改的文档。

POST /home.html
Content-Type: text/plain

Bob, please fix the spelling error in the title.  Thanks.

/home.html 标识我们正在修改的文档；正文告诉我们客户想要进行的修改。

统一的接口约束确保每个人（服务器、客户端、中间组件）都以相同的方式解释此消息——请求的语义在任何地方都是相同的，响应的语义也是如此。

请注意，我们不会将请求发送到/home.html?editor/home.html?operation=edit因为它们是两个不同的资源（我们知道这一点，因为标识符不同）。通过正确识别我们在请求中修改的资源，我们可以让通用组件清楚地知道发生了什么，这样它们就可以做一些智能的事情（比如使缓存失效）。

信息是否需要在“单独的对象”中是模式设计的问题；HTTP 真的不关心您在通过网络传输的文档中使用什么模式。

于 2021-04-16T22:46:29.280 回答
1

如果您只想使用 HTTP 作为传输机制，那么一切都会顺利进行。另一方面，如果你想开发一个真正的 RESTful API，你应该学习 REST。首先，考虑Richardson 成熟度模型。我不考虑 API RESTful，除非它是 3 级 API，但即使在 1 级，您也应该将 API 建模为一组资源。

每个资源都应该由一个唯一的 URL 标识，因此已经排除了 OP 中三个选项中的两个。

资源应该通过它们的 URL 来标识，但不是按照建议的那样。在第 2 级，动作由 HTTP 动词（GET、POST、DELETE等）指示。因此，为了支持创建订单，我设想这样的 HTTP 请求：

POST /orders HTTP/1.1
Content-Type: application/json
{
  "orderNumber": 1234
}

成功的请求应导致 200 范围内的响应（200 OK、201 Created等）。

相反，如果您想创建一个货件资源，您可以创建POST一个shipments收集资源：

POST /shipments HTTP/1.1
Content-Type: application/json
{
  "orderNumber": 1234
}

类似的资源orders通常shipments被称为集合资源，因为它们代表其他资源的集合。它们通常仅支持POSTandGET动词，其中GET将枚举集合中的所有资源。

每次POST针对集合资源通常会导致创建具有自己地址的“子资源”。例如，当您创建订单时，创建的地址可能是/orders/1234. 这样的资源通常会支持GET,DELETE和可能PUT, 但不支持POST.

我强烈推荐 Allamaraju Subrahmanyam 的书RESTful Web Services Cookbook给任何想要进入 REST API 设计的人。它易于阅读并且充满实用的解决方案。

于 2021-04-17T06:47:08.907 回答