Question

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

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

HAL spec给出了这个例子：

GET /orders

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

```

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

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

Answer 1

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

是的，当然。

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

这是人类和理想情况下甚至机器可以开始发现您的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 + JSON超媒体类型不是REST的媒体类型？

1 个答案: