HATEOAS 没有在响应中发送 HTTP 链接答案

【问题标题】：HATEOAS without sending the HTTP links in the responseHATEOAS 没有在响应中发送 HTTP 链接
【发布时间】：2018-01-11 10:53:33
【问题描述】：

您好 REST HATEOAS 专家！

这是来自 HATEOAS 服务的典型 JSON 响应

{
  links: {
     'add': 'http://myhost/API/students',
     'csv-export': 'http://myhost/API/students/export'
  },
  list: [
      {id: '1', name: 'John Doe', links: {'see': 'http://myhost/API/students/1'},
      {id: '2', name: 'Jane Doe', links: {'see': 'http://myhost/API/students/2'},
      ...
  ]
}

从这里我们可以看到发送完整的 HTTP(s) 链接以及响应是

非常占用空间（是的，我知道 gzip）
难以阅读（想象一下当列表中有 1000 个元素时）
还不够，因为您仍然不知道使用哪种方法（也不知道需要发送哪些内容）

所以我正在做的事情如下：

{
  resType: 'studentsCollection',
  rels: ['add','csv-export'],
  list: [
      {id: '1', name: 'John Doe', resType: 'studentCollectionItem', rels: ['see'],
      {id: '2', name: 'Jane Doe', resType: 'studentCollectionItem', rels: ['see'],
      ...
  ]
}

我提供了额外的端点： /resTypes/studentsColelction/rels

{
    resType: 'studentsCollection',
    links: {
       'add': {method: 'POST', url: '/students', contentType: 'studentForm', resultType: 'studentId'},
       'csv-export': {method: 'GET', url: '/students/export', contentType: 'studentCriteria', resultType: 'binary'}
    }
}

/resTypes/studentCollectionItem/rels { resType: 'studentCollectionItem', 链接：{ 'see': {method: 'GET', url: '/students/{id}', resultType: 'studentEntity'} } }

还有 /resTypes 一次返回所有 resTypes 以避免多次往返

【问题讨论】：

标签： hateoas

【解决方案1】：

听起来 JSON Hyper-Schema 非常适合您。 JSON Hyper-Schema 是一种超媒体媒体类型，可用于将链接应用到原始数据，而无需修改数据。

假设你有这个 JSON 响应数据

{
  "list": [
    {
      "id": "1",
      "name": "foo"
    },
    {
      "id": "2",
      "name": "bar"
    }
  ]
}

然后，该数据可以由以下超模式描述。

{
  "title": "Students",
  "type": "object",
  "properties": {
    "list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" }
        },
        "links": [
          { "rel": "student", "href": "/students/{id}" }
        ]
      }
    }
  }
  "links": [
    {
      "rel": "create", "href": "/students",
      "method": "POST",
      "schema": { "$ref": "/schemas/createStudent" }
    }
  ]
}

Hyper-Schema 就像一个超媒体模板，可应用于纯 JSON 文档，将纯 JSON 响应转换为启用超媒体的 JSON 响应。请注意示例 /students/{id} 中的 URL 模板。 {id} 变量是从实例数据中填充的。因此，列表中的第一项具有链接/students/1，第二项具有链接/students/2。这使您不必在每个响应中复制所有链接样板。

您使用标头链接将 JSON 响应与 Hyper-Schema 相关联

Link: </schema/students>; rel="describedby"

此时您可能会想，“这很好，但是为每个响应获取 Hyper-Schema 的额外请求比发送臃肿的响应需要更多的资源”。这就是为什么您应该设计您的系统，以便 Hyper-Schemas 可以永久缓存。然后，当客户端看到它已经拥有的资源的描述链接时，它只是使用它的缓存版本。无需额外请求。如果您需要更改 Hyper-Schema，只需将 describeby 链接更改为不同的 URI /schema/v2/student，客户端将一次性下载新的 Hyper-Schema。尽管偶尔会有额外的请求来检索 Hyper-Schema，但与在每个请求中发送所有链接相比，您的总体带宽使用量应该会更少。

此示例使用draft-04 版本的 JSON 超模式。可以说，自 04 草案以来，JSON Schema 一直处于“新管理之下”。尽管 draft-04 远非完美，但我个人对他们自 04 草案以来采用的规范方向并不满意。不过，我鼓励您也查看最新的草稿（当前为 draft-07）并做出自己的决定。

【讨论】：