如何为机器和人类使用一个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"
        },
        ...
    ]
}

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

这是一个明智的设计吗？为什么或者为什么不？有没有受欢迎的网站呢？

我看到的最大缺点是用户没有明显的方法来删除资源.在我的用例中,我不会让用户修改或删除资源,所以这不是一个交易破坏者,但总的来说你怎么处理？

Answer 1

@mehaase

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

• Collection + 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(或其他格式).

我看到的最大缺点是用户没有明显的方法来删除资源.在我的用例中,我不会让用户修改或删除资源,所以这不是一个交易破坏者,但总的来说你怎么处理？

对于这个读取"编辑"链接关系规范,它意味着可以删除资源.