HAL+JSON 超媒体类型不是 REST 的媒体类型？答案

【问题标题】：HAL+JSON hypermedia type not a media type for REST?HAL+JSON 超媒体类型不是 REST 的媒体类型？
【发布时间】：2017-01-18 18:11:18
【问题描述】：

HAL+JSON 超媒体类型能否用于创建 RESTful 服务？

根据我的阅读，RESTful API 的客户端不需要处理特殊情况下的不同资源。应该使用媒体类型来描述资源的预期外观。

HAL spec 给出了这个例子：

GET /orders

{
  ...
  "shippedToday": 20,
  ...
}

```

作为此示例 HAL+JSON 服务 API 的客户端，我似乎需要知道“订单”的属性为 shippedToday。这似乎违背了客户端不需要理解表示的语法的约束。

这不是对 HAL 的批评。问题是帮助我（和其他人）理解 RESTful API 设计。

【问题讨论】：

标签： api restful-architecture media-type

【解决方案1】：

HAL+JSON 超媒体类型能否用于创建 RESTful 服务？

是的，当然。

API 应该有一个广告牌 URL，在您的情况下可以是 /。

这是人类甚至机器可以开始发现您的 API 的入口点。

根据HAL specification，资源表示包含一个名为"_links" 的可选属性，如下所述：

它是一个属性名称为链接关系类型的对象（如由RFC5988) 定义，值是链接对象或数组链接对象。

因此，这些链接代表 API 的超媒体部分。关系可以是IANA-注册关系，也可以使用自己的扩展关系。

关系不应模棱两可。他们的名字应该是唯一的。这就是为什么建议使用您自己域中的 URI 作为您自己关系的名称的原因。这些 URI 标识代表关系的资源，并包含 API 文档、人类或机器可读的关系文档。

在您的情况下，这将是描述状态转换到/orders 资源的关系。这还应包括对响应的描述和解释，因此记录例如/orders 资源表示订单列表，并有一个名为“shippedToday”的属性，其值为 number。

这是GET / HTTP/1.1 请求的示例响应：

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links": {
        "self": { "href": "/" },
        "http://yourdomain.com/docs/rels/orders": { "href": "/orders" },
    }
}

http://yourdomain.com/docs/rels/orders 下应该有 API 文档。

【讨论】：

我已经读了几遍了，它并没有真正加深我对 HAL _links 提供的内容的理解。您是说我应该从 _links 属性中了解我应该阅读“/docs/rels/orders”提供的文档以了解“/orders”URL 是如何在订单上提供 CRUD 功能的 HAL 端点集？我似乎违反直觉，我应该使用属性的标签作为 URL。
@Adam 是的，这确实有点违反直觉。据我所知，您对它的理解是正确的。为了使链接关系类型更具可读性，您可以使用 CURIE（请参阅 stateless.co/hal_specification.html）。