24

我刚刚开始为我目前正在构建的 WebAPI 编写客户端实现。API 已经使用了 HATEOAS,所以我正在相应地编写客户端。我使用RestSharp作为客户端的基础。

客户端在构建时(“ https://myapi/start ”)传递了 api 基本 URL,它会在该 URL 处触发请求,然后传递一组用于其他可用资源的 uri - 授权(“ https://myapi/ authorize ") 并请求访问令牌 (" https://myapi/tokens ") 以授权它调用 api 上的安全资源。

问题是对于返回的超媒体中的 rel="" 要求是否制定了任何标准?

4

5 回答 5

16

我相信超文本应用语言(HAL) 是一个标准草案——试图标准化超媒体之间的这些链接。

这是 JSON 规范草案的链接https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-03

HAL 规范强制“href”符合 Web 链接规范 (RFC 5988) 中定义的“目标 IRI”

这里有一个使用 C# 的 HAL 的 XML 实现https://github.com/tavis-software

上面相同的 GitHub 存储库还包含 RFC 5988 的示例 .Net 实现。

于 2012-11-14T14:57:04.553 回答
11

正如另一个答案中所指出的, Web 链接规范 RFC5988定义了一些不同类型的链接关系。但它也指示 IANA 创建链接关系注册并允许进一步的链接关系注册。该注册表是公共链接关系最终列表,可在iana.org/assignments/link-relations上找到,并将随着新关系的注册而更新。

HTTP API 中常用的关系包括:

  • start(从每个资源指向 API 起点)
  • item(从集合指向项目,例如从 Twitter 用户页面指向推文)
  • collection(反面item
  • previous(接下来的四个用于分页资源,例如集合或多页文章)
  • next
  • first
  • last
  • create-form(从集合指向描述如何创建新集合项的资源,例如“新项”HTML 或 XForms 表单)
  • edit-form(从项目指向用于编辑该项目的表单,例如“编辑推文”按钮)

如果该列表中的任何内容均未涵盖您所需的关系,则您的关系必须是 URI。此外,建议在您控制的域中将该 URI 设置为可取消引用的 http URL,以便 API 客户端可以查找该关系的文档,例如http://www.example.com/link-relations#tweets. 通常,您的 API 起点将是一个集合列表,每个集合都有一个自定义链接关系,描述每个集合包含的资源类型。

于 2012-12-03T15:18:27.250 回答
7

在进一步讨论 HATEOAS 标准之前,我想强调在实现 HATEOAS(现在也称为超媒体 API)的 API 中有三个主要概念:

  • HTTP 协议。在使用动词和返回码时,您必须尊重其约束。您还应该知道标题的作用,尤其是Content-type,以及一些动词的幂等性等微妙之处。有关更多信息,请参阅 RFC 2616
  • URI 结构。必须只提供有关定位资源的信息,并避免使用上下文数据。例如,已知的不良示例包括 language /en/、 version /v01/、 format/json/甚至/do-something/是 URI 中的动词。更多关于 RFC 3986 和 REST 指南
  • 上下文数据,可以在正文、请求参数或标头中找到

REST 库的开发人员对 URI 和 HTTP 有严格的指导方针,但缺乏关于上下文数据以及它如何与请求的 JSON 正文中的应用程序数据混合的通用标准。

这就是为什么围绕 HATEOAS 的标准化工作主要是关于制定media-type. 旁边有好几个

  • 由 Mark Jones 概述的JSON HAL(约 2012 年)是最著名的
  • Collections + JSON (ca 2013),没有引起太多关注
  • 详细(ca 2014)试图统一其他所有努力,但只有专家知道
  • Siren (ca 2017) 在 github 上有大约 1k 颗星
  • JSON:API(约 2015 年,但仍在进行中)是当前参考,其 1.0 版有很多实现,并得到了 Steve Klabnik 的支持,他围绕该主题创作了大量内容

关于您的原始问题,请参阅此处JSON:API了解有关相关资源链接的说明。

希望这将帮助任何在 2019 年有同样担忧的人。

于 2019-02-01T15:36:29.423 回答
5

这个 IETF 提议的标准RFC5988 文档描述了不同类型的链接关系和提议的用法。它的重点是 HTTP 链接头规范,但它包括对其他链接关系类型的讨论。像一些(大多数?)RFC 一样,阅读它可能会让您比刚开始时更加困惑,但从长远来看,它值得付出努力。它会回答您问题中双引号之间的内容吗?可能不会,但至少你会得到一些想法来指导你的选择。

于 2012-11-14T14:51:31.433 回答
2

HAL 看起来确实很有趣。

对于其他研究此主题或 HATEOAS 的人来说,HAL 浏览器是必须的。查看以下链接:

Heroku 上的 Hal 浏览器

于 2012-11-14T15:10:33.237 回答