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

Question

能否以创建 RESTful 服务的方式使用 HAL+JSON 超媒体类型？

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

HAL spec给出了这个例子：

GET /orders

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

```

作为这个样本HAL+JSON-serving API的客户端，我似乎需要知道一个"order"有一个shippedToday的属性。这似乎违背了客户端不需要理解表示语法的约束。

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

Answer 1

Can the HAL+JSON hypermedia type be used in a way that creates a RESTful service?

是的，绝对是。

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

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

根据 HAL specification，资源表示包含一个名为 "_links" 的可选属性，在此处进行了描述：

It is an object whose property names are link relation types (as defined by RFC5988) and values are either a Link Object or an array of Link Objects.

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

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

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

以下是 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+JSON 超媒体类型不是 REST 的媒体类型？

HAL+JSON hypermedia type not a media type for REST?

api

media-type

restful-architecture