设计一个RESTful api 用于一次创建资源及其相关资源

Question

我想知道如何设计一个RESTFULapi一次性创建资源及其相关资源

例如，我想使用我的 RESTFUL API 创建一个包含项目列表的订单，例如：

{
    order_id:1,
    description: "XXX",
    items: [
        {item_id:1, price:30, ...},
        {item_id:2, price:40, ...}
    ]
}

一种方法是给两个 api

post: api/orders => 创建一个新订单和 return 订单 ID
post: api/orders/id/items => 使用 order_id

但是，订单和项目应该一起创建。因此，如果第二个 api 失败，它将创建一个没有任何项目的订单，这是我不想看到的情况。其实我是想让后台服务器做一个事务，一次创建订单和商品，应该一起成功，一起失败。

那么，将项目放在请求正文中，并且 post 只到 api/orders 一次是不是一个好方法？或者对于这种情况还有其他更好的设计吗？

谢谢！

Answer 1

当然，创建没有项目的订单 - 坏主意。这将以不可靠的 API 和不一致的实体结束。此外，您不能使用 api/orders URI 创建项，因为这违反了 REST 原则的基础。

对于您的业务逻辑 REST API 可能如下所示：

POST api/item
  {
    price: 40,
    name: "xxx",
    ...
  }
<<<<< 201
  {
    id: 1
  }

GET api/item/{id}
<<<<< 200
  {
    id: 4,
    price: 40,
    name: "xxx",
    ...
  }

POST api/order
  {
    description: "xxx",
    items: [
      {id: 1, count: 5},
      {id: 23456, count: 1}
    ]
  }
<<<<< 201
  {
    id: 123442
  }

我认为在创建订单请求正文中没有必要将完整的项目放入。商品 ID 足以在后端创建订单商品绑定。

Answer 2

I want to know how to design a RESTFUL api for creating a resource and its related resources at once.

非常合理的事情。将注意力集中在如何向客户描述如何创建适当的请求，以及如何解释描述结果的文档。

线索在 201 Created 状态码的定义中

The 201 (Created) status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The 201 response payload typically describes and links to the resource(s) created.

（强调）

在网络的情况下，我们这样做的方式是有一个表单；客户将在表格中提供信息并提交。浏览器遵循表单处理标准，将生成一个 POST（因为语义不安全）请求，其中表单数据编码在消息 body 中，适当的内容类型定义在 header（例如application/x-www-form-urlencoded）。

响应，在术语中，将是一个 HTML 文档，其中包含指向所有已创建的有趣资源的链接。

一定要HTML吗？不，当然不是 - 如果满足您的需要，您可以使用 text/plain。当使用内置了通用组件可以理解的链接概念的媒体类型时，您会有更好的长期前景。

设计一个RESTful api 用于一次创建资源及其相关资源

Design a RESTful api for creating a resource and its related resources at once

api

rest

post

one-to-many

orders