RESTful API 是否应该避免要求客户端知道资源层次结构？答案

【问题标题】：Should a RESTful API avoid requiring the client to know the resource hierarchy?RESTful API 是否应该避免要求客户端知道资源层次结构？
【发布时间】：2017-05-19 09:35:46
【问题描述】：

我们 API 的入口点有一个名为“x:reports”的 rel（其中 x 是在 HAL 表示中定义的前缀，通过居里表示 - 但现在这并不重要）。

报告有多种类型。后面的“x:report”提供了一组这些可供性，每个都有自己的 rel - 一个 rel 被命名为“x:proofofplay”。有一组与这种类型的报告相关联的查找值（并且只有这种类型的报告）。跟随“x:proofofplay”返回的表示与这组值“x:artwork”有一个关系。

这会产生以下层次结构

reports
  proofofplay
    artwork

虽然“x:artwork”资源相当小，但获取它确实需要一些时间（10 秒）。所以客户端选择在应用启动时异步加载它。

为了获得“x:artwork”的href，客户必须点击链接。我不确定这是否是个问题。它似乎可能是不稳定的，因为客户端依赖于该资源路径的带外知识。如果艺术作品的路径发生变化（极不可能），客户端将会中断（尽管 href 本身可以不受惩罚地改变）。

要了解我为什么担心，启动功能如下所示：

launch: function () {
    var me = this;
    Rest.getLinksFromEntryPoint(function(links) {
        Rest.getLinksFromHref(links["x:reports"].href, function(reportLinks){
            Rest.getLinksFromHref(reportLinks["x:proofofplay"].href, function(popLinks){
                me.loadArtworks(popLinks["x:artwork"].href);
            });
        });
    });
}

路径的这种硬编码同时让我觉得“这很好 - 它基于已发布的资源模型”和“我敢打赌 Roy Fielding 会生我的气”。

这样可以吗，还是有更好的方法让客户安全地浏览这样的层次结构？

【问题讨论】：

标签： rest hypermedia

【解决方案1】：

HAL 对此的回答是嵌入资源。

根据您的服务器端技术，这在您的情况下应该足够好，因为您需要在应用程序启动之前将所有数据都存在，并且由于您担心按顺序执行此操作，您可以并行化此操作在服务器上。

理想情况下，您的 HAL 客户端应将 _links 中的内容和 _embedded 中的内容视为同一类型的事物，除了在第二种情况下，您还按每个填充资源的 HTTP 缓存。

我们基于 js 的客户端执行如下操作：

var client = new Client(bookMarkUrl);
var resource = await client
  .follow('x:reports')
  .follow('x:proofofplay')
  .follow('x:artwork')
  .get();

如果_links中指定了这些中间链接中的任何一个，我们将按照链接并按需执行GET请求，但如果_embedded中出现任何中间链接，则跳过该请求并使用本地缓存.这样做的好处是，将来我们可以将新的东西从_links 添加到_embedded，并加快不必知道此更改的客户的速度。这一切都是无缝的。

未来我们打算从 HAL 的 _embedded 切换到使用 HTTP2 Push。

【讨论】：