使用子元素设计rest服务的最佳实践

Question

我正在设计一个REST服务，它需要创建一个作为子级引用各种其他项的项。该服务提供了作为选项检索可用子级的方法，这些选项可以以键/值对的形式绑定到下拉列表。我的问题是，当发布来创建新的顶级项时，最佳做法是将整个子项包含在字段中，还是只包含引用它的ID？

例如，如果我有一项服务，使用户能够为笔记本电脑指定处理器和RAM。有一个方法GET /processors将返回处理器列表，并发布触发对象创建的/laptops。以下两个有效载荷中的哪一个被认为是最佳实践？

POST /laptops

{
    "processor": 123,
    "ram" 16
}

POST /laptops

{
    "processor": {"id":123, "manufacturer": "Intel", "model": "i5-4670k"}
    "ram" 16
}

在检索笔记本电脑时，我会返回如下内容：

获取/laptops

[{
    "id:" 3000,
    "processor": {"id":123, "manufacturer": "Intel", "model": "i5-4670k"}
    "ram" 16
}]

Answer 1

如果用于构造膝上型计算机的所有部件都是预先定义的(或者已经存在)，最好只使用部件的ID。因此，将是：

POST /laptops

{
    "processorID": 123
}

为什么？因为这样可以节省带宽并简化服务器端的验证。与其检查处理器的所有字段，不如只检查是否存在具有给定ID的进程-如果没有，应该返回409 CONFLICT。

如果您希望使用户能够在膝上型计算机创建过程中创建，那么应该发送特定部件的整个主体。然而，这不是一个好主意。在RESTful方法中，您应该创建所有的部件，然后创建一个膝上型计算机--指向上一段。

最重要的是以一致的方式设计API --在所有端点中以相同的方式进行设计。

现在，在返回笔记本电脑时，最好也只返回ID。这种方法将与创建新实体(仅发送ID )兼容，但带宽参数可能有点误导-客户端需要发出多个请求才能获得所有部件的详细信息。所以..。在本例中，我将添加名为format的查询参数，它接受两个值SIMPLE (默认值)和EXTENDED。如果传递SIMPLE，则只返回ID，如果传递EXTENDED，则返回整个实体。