REST 超媒体 API - 从无状态客户端导航

Question

一个直截了当的问题:如果我正在构建一个无状态客户端，它会在请求之间“更改页面”，我该如何正确使用超媒体 API？

当然，一个关键点是客户端不应该构造 URL。例如，如果我们要获取某种集合(比如说水果)，每个集合条目都会有一个 URL 以链接到 API 中的单个水果资源。太好了。

[ { "name": "Apple", "url": ".../fruits/15" } ]

但是在我的客户中，在呈现水果列表后，我希望将该列表链接到另一个包含水果详细信息的前端页面。这样的详细信息页面当然应该可以添加书签等。我意识到，从哲学上讲，前端 URL 的精确结构并不重要 - 但它对下面的问题具有实际意义。

<a href="?">Apple</a>

那么问题是，在加载水果详情页面时，没有当前上下文的客户端如何决定要获取的 API URL？

/my/frontend/stuff/fruits/{?}

现在怎么办？

最初想到的解决方案是在集合响应中有一个“项目”URL 模板，并使用其中的命名参数来构造页面 URL。然后，详细信息页面将查询 API 以恢复相同的“项目”URL 并植入传递给它的参数。这看起来并不理想，但它确实实现了所需的解耦。

提前致谢。

Answer 1

网络浏览器是许多用户最熟悉的无状态客户端。您所要求的称为 URI 模板，并受各种超媒体格式的支持。例如，在 HTML 中:

<form action="/api/fruits" method="GET">
  <input type="number" name="id" value="1" min="1">
  <button type="submit">Get Fruit</button>
<form>

当然会在提交时生成对 URI /api/fruits?id=1 的 GET 请求。

其他超媒体格式 such as HAL允许在 URI 中的任何位置进行模板化，并且比 HTML 更适合 Web 应用程序。您需要研究您首选的超媒体表示格式支持的模板机制，或者切换到支持您需要的格式。

当然，由于模板设计不佳，在 HTML 中，我们必须列出每个需要的 URI 并对长列表进行分页:

<a href="/api/fruits/1/">Apple</a>
<a href="/api/fruits/2/">Banana</a>
<a href="/api/fruits/3/">Citrus</a>
...
<a href="/api/fruits/?page=2" rel="next">Page 2</a>

老实说，如果用户要直接输入 ID，您可能也应该允许 HTML 和查询字符串参数。当第三方客户端开发人员针对您的 API 进行构建时，它会有所帮助，如果您需要与最终用户进行调试，它的可用性也会有所帮助。只需将他们指向一个 URL 并询问“如果你去这里有用吗？”