Hypermedia 简介

参考：Blog of Michael Scharhag 的博客

带链接的资源表示形式

让我们从一个没有超媒体的简单示例开始。假设我们要创建一个资源，提供有关订单的信息。它可能看起来像：

GET /orders/123

{"buyer_id": 456,"order_date": "2020-15-08T09:30:00","total_price": 4.99,"payment_date": null,"status": "open","items": [{"product_id" : 789,"quantity": 1,"price": 4.99}]
}

请注意，buyer_id product_id引用其他资源。如果客户端想要获得有关买方的更多信息，它必须构建一个这样的新请求 URI：

1	`String buyerUrl =` `"/customer/"` `+ order.getBuyerId();`

在这里，客户端必须知道相关资源的确切 URI 格式。这类似于不使用超链接浏览网页。而不是点击链接，我们必须手动更新浏览器请求行，为每个子页面，我们要访问。

要将 Hypermedia 支持添加到我们的订单表示中，我们必须将 ID 替换为指向相关资源的链接。

例如：

{"buyer_url": "/customers/456","order_date": "2020-15-08T09:30:00","total_price": 4.99,"payment_date": null,"status": "open","items": [{"product_url" : "/products/789","quantity": 5,"price": 4.99}]
}

我们现在在相关资源之间创建了链接。客户端不再需要关心 ID 和 URI 构造。要获取买家信息，客户只需向价值为一个客户buyer_url。

超媒体响应格式通常在单独的 JSON 对象中将链接分组在一起。使用 JSON 对象表示链接也是一个好主意。这为我们提供了以后向链接添加更多信息的选项。

如果我们将其应用于订单表示形式，则可能看起来像：

{"order_date": "2020-15-08T09:30:00","total_price": 4.99,"payment_date": null,"status": "open","items": [{"quantity": 5,"price": 4.99,"links" : [{ "rel": "product", "href": "/products/789" }]}],"links" : [{ "rel": "buyer", "href": "/customers/456" }]
}

使用rel 字段，我们描述资源关系的类型，而 href包含实际链接（稍后将详细介绍）。

状态转换（HATEOAS）

到目前为止，我们只使用链接来指示与其他资源的关系。链接还可用于指示对资源的可能操作。例如，可以支付和取消订单。我们可以使用链接指向这些操作：

{"order_date": "2020-15-08T09:30:00","total_price": 4.99,"status": "open","payment_date": null,"items": [ ... ],"links" : [{ "rel": "buyer", "href": "/customers/456" },{ "rel": "payment", "href": "/orders/123/payment" },{ "rel": "cancellation", "href": "/orders/123/cancellation" }]
}

为了取消订单，我们现在只需向取消链接发送 PUT请求。取消订单后，资源表示形式可能看起来像：

{"order_date": "2020-15-08T09:30:00","total_price": 4.99,"status": "cancelled","payment_date": null,"items": [ ... ],"links" : [{ "rel": "buyer", "href": "/customers/456" },]
}

请注意，订单状态已更改，取消和付款的链接已消失。当然，取消的订单不能再取消，支付取消的订单是没有意义的。因此，链接不仅指向操作，还告诉我们在当前资源状态下哪些操作是可能的。

这被称为Hypermedia as the Engine of application State （Hateoas）。HATEOAS 可以通过 HTTP 将 REST API转换为状态机。

有关链接的更多

到目前为止，我们使用了相当多的链接。所以，研究一些细节是一个很好的观点。

链接属性rel 和 href来自 HTML 中用于表示链接的<a> 标记的属性。IANA 已标准化了一组常见的链接关系（如第一、下一个、上一个等）。你可以在 IANA 网站上找到这些关系。在想出自己的新 rel 类型之前，先看一下此列表是一个好主意。

也是个好做法，包括指向当前资源（名为 self ）的链接。例如：

GET /orders/123

{..."links" : [{ "rel": "self", "href": "/orders/123" },...]
}

链接可能并不总是指向精确资源。还可以创建包含占位符或可选参数的链接。例如，订单列表可能包含包含状态请求参数的状态搜索链接：

GET /orders

{..."links" : [{ "rel": "self", "href": "/orders" },{ "rel": "search-by-status", "href": "/orders{?status}" },...]
}

客户端可以使用该链接按特定订单状态筛选订单列表。例如，这可能是一个有效的请求：

GET /orders?status=open

这些模板称为 URI 模板（在RFC 6570 中定义）。RFC 是更多信息的一个很好的来源。

链接也是 API 文档的重要组成部分。您应该记录资源的可能链接关系，而不是记录精确的资源 RBI。客户端需要知道特定链接执行什么操作以及如何使用它（HTTP 方法、请求正文（如果需要）等）。

API 入口点

如果客户端不知道任何资源 RBI，则需要一些初始请求的入口点。然后，此初始入口点提供指向可访问资源的链接。我们的示例 API 的 API 入口点可能看起来像：

GET /

{"version": "1.2.3","description": "Example API to manage orders","links": [{ "rel": "orders", "href": "/orders" },{ "rel": "customers", "href": "/customers"},{ "rel": "customer-by-id", "href": "/customer/{id}"},{ "rel": "customer-by-email", "href": "/customer{?email}"},...]
}

使用 URI 模板，我们可以确保客户端不需要浏览大型集合来查找所需的资源。