Rest API Hateoas：API 响应应该将标识符作为硬编码还是作为占位符？

Question

Link to the HATEOAS This is the link to the Hateoas article (snapshot below) where the identifiers of the resource is part of the URL ie 12345. Here the API response has the final API relative URL ie /accounts/12345/deposit and the client只需要击中它。

Link to the Github Users API This is the link to the Github API (snapshot below) where there are lots of placeholders for identifiers. 客户端将如何修改这些 URL 并在这些占位符中添加值？ 例如，{/gist_id}、{/other_user}。

传递带有 id 值而不是占位符的 URL 不是更好吗？ 为什么以及何时依赖不同的客户端在这些占位符中添加值？

Answer 1

超文本作为应用程序 state (HATEOAS) 的引擎不仅仅是使用链接。 从本质上讲，它非常成功地执行了在 Web 上使用了二十年的交互 model。 在 web 上，服务器通常“教”客户端（浏览器）通过链接关系实现某些目标，可用于自动下载相关资源或提示参考资源，以及Web ZAC68B6236C和 8A9FECZE8ACCE 定义语法每个支持的（输入）元素的语义，即文本字段，select 一个或多个选择的选项元素，下拉菜单甚至 slider 小部件。 基于每个元素的可供性，客户端知道，即按钮想要被点击或按下，而文本字段想要一些用户输入和东西或带有prefetch链接关系名称注释的链接可以在当前页面自动下载完成加载，因为客户端可能会在接下来调用它，或者preload链接关系可能会指示用户代理在当前页面加载过程的早期加载引用的资源。

该表单不仅向客户端介绍了资源具有的支持字段，还向客户端介绍了将请求发送到的目标 URI、HTTP 方法在发送请求时使用的方法以及媒体类型，在 Web ZAC68B62ABFDC68ACCE0C26 的情况下通常隐式设置为application/x-www-form-urlencoded 。

在理想世界中，客户端只使用服务器提供的信息。 不幸的是，世界并不完美，随着时间的推移，人们提出了许多其他解决方案。 其中之一是URI 模板，它基本上允许客户端使用基本 URI 并用具体值填写某些占位符。 由于使用模板需要了解 URI 意图或您需要传递的参数，因此此类功能仅作为媒体类型支持的一部分才有意义。

普通 JSON ( application/json ) 默认情况下不支持任何 URI，因此接收普通 JSON 有效负载的用户代理可能无法自动用开箱即用的具体 URI 替换模板 URI。 JSON Hyper-Schema ( application/schema+json ) 尝试将链接和 URI 模板支持添加到普通的 JSON 有效负载中。 但是，用户客户端需要使用适当的媒体类型来提示，以便自动解析完整的 URI。 因此，用户代理还必须支持相应的媒体类型，否则它将无法成功处理文档（将模板 URI 解析为真实 URI）。

JSON 超文本应用语言又名HAL JSON也支持链接的 URI 模板。 application/collection+json确实支持两种模板—— 查询模板和对象模板。 引物类似于 URI 模板，允许 append 在发送请求时向目标 URI 提供某些查询参数，而后者允许定义整个 object，其中包含用于在集合中添加或编辑项目的所有输入元素. JSON-LD并不真正支持 URI 模板 AFAIK，尽管它使用所谓的上下文的概念，其中某些术语可用于缩写 URI。 因此，可以在诸如http://schema.org/name之类的 URI 的上下文中使用诸如name之类的东西。

如您所见，对 URI 模板的支持取决于用于交换数据的媒体类型。 In the case of the outlined github example GET /users/:username this more or less resembles a typical Web API documentation, similar as it is done in a Swagger API documentation , that unfortunately has hardly anything to do with HATEOAS .

Answer 2

对于您的顶级示例（银行），您绝对应该包含完整的 URL 和帐号（ID），以便客户不需要翻译/替换任何内容。 这是 HATEOAS 最常见的情况。 但是，GitHub 确实为可能包含多个值的端点提供了那些“占位符”。 您不能在响应中包含每个用户的“following_url”，这是不切实际的。 因此，您必须以另一种方式确定“other_user”值并进行替换。 就个人而言，我的任何应用程序都没有这个用例，而且我所有的 HATEOAS URL 都类似于您的第一个示例（尽管我更喜欢完整的 URL，而不是相对的）。 除非你有像 GitHub 这样的特殊情况，否则没有必要使用这些占位符。 即使是 GitHub 也只使用它们可能是多个值的地方。 对于固定值 URL，它们在 URL（“octocat”）中具有用户名（如您的帐号）。

Answer 3

根据我的说法，我们不应该在正文中直接给出 url 我们应该始终参数化 api 并在那里获取详细信息。 在简单的情况下，如果数据 ID 发生变化，则每次数据都需要更新详细信息 url。 否则，如果它是动态的，您将永远不会遇到这个问题。 这也属于最佳实践。