你是对的,有很多混乱。专家通常将“真正的”REST API 称为 HATEOAS 或超媒体驱动的 API,以避免这种混淆。大多数 API 都是这样的do自称 REST api 的通常不是。
因此,当与其他工程师讨论 REST api 时,首先澄清每个人认为的 REST 和非 REST 是有帮助的。他们并不是不知道的坏工程师,“REST”这个术语有自己的生命,我想说 HATEOAS 可能更多的是一种小众技能。
我同意尼古拉斯·尚克(Nicholas Shank)的回答,在许多情况下,普遍要做的事情是弄清楚是否例如DELETE
有效,就是实际发出DELETE
看看之后是否有效。
但这并不总是有帮助,因为许多构建 API 的人希望不显示“删除”按钮(如果它无论如何也不起作用)。
那么什么是合理的方式告诉客户DELETE
有空吗? HTTP 标准实际上确实有一个Allow您可以使用该标头来了解哪些方法适用于给定端点。要了解这些是什么,您可以发出OPTIONS
要求。并非每个框架都支持开箱即用,但这是一种合法的方法。
提前告诉客户的另一种方法是将此信息嵌入到您正在访问的资源中。举几个例子:
-
链接提示 https://datatracker.ietf.org/doc/html/draft-nottingham-link-hint-01是一个互联网标准草案,可以在各种不同的地方提供这些提示,例如 HAL、HTTP 链接标头或其他。它基本上建议了该信息的通用格式。
- 如果您使用 OpenAPI 之类的东西,您可以在 API 规范中添加哪些方法可以工作,哪些方法不能工作。这对于您知道的情况非常有效
DELETE
永远不会起作用,但在不同用户可能具有不同级别的访问权限并且有些人可以使用的情况下,它不会真正帮助您DELETE
而其他人则不能。
- 您可以将此信息嵌入到您自己的格式中,将其表示为一组权限,可能采用 JSON 格式,您的应用程序可以理解该格式来解释是否可以执行某些操作。
- 某些 HATEAOS 格式明确嵌入了有关可以通过操作采取何种操作的信息。一个很好的例子是SIREN https://github.com/kevinswiber/siren格式。 HAL 本身没有这个。
最终,良好的 HATEAOS 格式不仅会返回有关资源和与其他人的关系的信息,还会给出一组可以采取的潜在操作。大多数 REST APIareHATEOAS 往往不这样做,但 HTML 是这样做的最好例子。如果没有执行操作的链接、按钮或表单,用户就无法发现该操作。
嵌入 HAL 中的链接提示示例
{
"_links": {
"self": {
"href": "/orders/523",
"hints": {
"allow": ["GET", "DELETE"],
}
}
}
}
警报器示例
{
"class": [ "order" ],
"properties": {
"orderNumber": 523,
},
"actions": [
{
"name": "delete-order",
"title": "Delete Order",
"method": "DELETE",
"href": "/orders/523",
}
],
"links": [
{ "rel": [ "self" ], "href": "/orders/523" },
]
}
选项响应
HTTP/1.1 200 OK
Allow: GET, DELETE