rest - 如何为机器和人类使用同一个 REST API？

Question

我有兴趣使用 REST API 构建 Web 服务。我一直在阅读有关 HATEOAS 的内容，其中许多示例通过将其与人类上网时的行为进行比较来解释这个概念。这让我思考，为什么不以人类和机器都可以轻松使用的方式构建 REST API？

例如，我有一个小部件的内部模型，该小部件具有部件号、价格等属性。当机器请求小部件列表时，我可以返回 JSON 表示形式。

{
    widgets: [
        {
            id: 1,
            part_number: "FOO123",
            price: 100,
            url: "/widget/1"
        },
        {
            id: 2,
            part_number: "FOO456",
            price: 150,
            url: "/widget/2"
        },
        {
            id: 3,
            part_number: "FOO789",
            price: 200,
            url: "/widget/3"
        },
        ...
    ]
}

当人们通过他/她的网络浏览器请求相同的列表时，我似乎应该能够采用相同的内部模型并对其应用不同的 View 以生成 HTML 响应。 (当然，我会用其他页面元素来装饰 HTML 响应，例如页眉、页脚等)

这是一个明智的设计吗？为什么或者为什么不？是否有任何流行的网站实际上在这样做？

我发现的最大缺点是用户没有明显的方法来删除资源。在我的用例中，我不会让用户修改或删除资源，因此这不会破坏交易，但一般来说您会如何处理？

Answer 1

@mehaase

首先，我建议使用注册的 JSON 超媒体格式之一:

• 集合+JSON:http://amundsen.com/media-types/collection/format/
• Collection.next+JSON: http://code.ge/media-types/collection-next-json/
• HAL - 超文本应用语言: http://stateless.co/hal_specification.html

它们都提供了用于创建具有语义链接关系的链接的显式语义。

例如，使用 Collection(.next)+JSON，您可以像这样表达您的小部件:

{"collection": {
  "version": 1.0,

  "items": [{
    "href": "/widget/1",

    "data": [{
      "name": "id",
      "value": 1,
      "prompt": "ID"
    }, {
      "name": "part_number",
      "value": "FOO123",
      "prompt": "Part number"
    }, {
      "name": "price",
      "value": 100,
      "prompt": "Price"
    }],

    "links": [{
      "rel": "self",
      "href": "http://...",
    }, {
      "rel": "edit",
      "href": "http://..."
    }]

  }]
}}

这给您带来了几个优势:

• 您无需重新发明轮子来指定链接
• 您可以自由使用所有已注册的链接关系类型: http://www.iana.org/assignments/link-relations/link-relations.xml
• 根据您的数据结构，您可以轻松使用上述格式的集合/项目语义
• 如果需要，您也可以描述输入表单

正如您从示例中看到的，它有足够的信息可以转换为 HTML(或其他格式)。

The biggest drawback that I see is there is no obvious way for a user to delete a resource. In my use case, I'm not going to let users modify or delete resources, so this is not a deal-breaker, but in general how might you handle that?

对于这个读取“编辑”链接关系规范，它意味着资源可以被删除。