API应该自行消耗还是直接为其他资源调用数据库？

Question

这个问题是一个扩展,尽管之前发布了这个问题.

所以我们有一个车库有几辆车的基本例子,所以我们的终点是

/garages
/garages/{id}
/garages/{id}/cars
/garages/{id}/cars/{id}
/cars
/cars/{id}

我们可以从多个车库获得所有车辆 /cars?garage[id]=1,2,3

这很酷.但我现在想知道的是在API的内部.

我有两种方法可以做到这一点:

在/ cars端点中直接过滤

这意味着我们在查询中获取我们做某些连接的汽车并添加到某些地方.

这种方法的好处是我们最终会得到最少量的查询.
这种方法的结果是我们最终在两个地方维护车库资源.任何时候车库获得一个新的财产,我们现在必须支持汽车终端.

从/ cars端点调用/ garages端点

这意味着我们在/ cars端点内调用/ garages端点,/ garages从匹配的车库返回所有汽车的id.然后我们继续从/ cars端点返回汽车.

这种方法的好处是资源是自包含的.
这种方法的结果是我们最终将对数据库进行多次调用.传递身份验证细节也会变得很麻烦(让我们假设Oauth 2.0)

那么最合适的方法是什么？我倾向于第二种方法但是我担心如果我们想要做一些更高级的查询,这可能会成为一个真正的麻烦.

Answer 1

使用您自己的端点（这称为服务分层，有很多好处），但不要与您的端点紧密耦合。

首先，我不会通过数字 ID 进行查询，因为这与您的实现紧密相关。如果您使用 URL 作为车库标识符，那么您将获得更大的灵活性，并且可以轻松地在您自己的系统之外的其他系统中添加对车库的支持。

使用超媒体控件（即链接和表单）在汽车列表上添加搜索表单。假设您的汽车列表看起来像这样（为简洁起见，排除了方案和主机）

<cars self="/cars">
    <car href="/cars/0"/>
    <car href="/cars/1"/>
    ...
</cars>

注意：您需要向汽车添加一些摘要属性（例如注册、品牌、型号等，以使搜索有意义，而不必返回完整的汽车实体）。

要添加搜索，我们可以添加类似的内容

<cars self="/cars">
    <car href="/cars/0"/>
    <car href="/cars/1"/>
    ...
    <form name="search" action="/cars" method="get">
        <input name="garage" type="URL"/>
        <!-- other things to search for can go here -->
    </form>
</cars>

在您的资源存储库（例如数据库）中，如果您的汽车存储了它们所在车库的 URL，则可以执行此查询，而根本不需要查询车库，并且如上所述，支持在完全不同的系统中拥有车库，假设其他系统使用您的媒体类型或您支持他们的媒体类型。

显然，您在搜索时需要访问车库 URL，这也可以通过车库搜索来完成。例如

<garages self="/garages">
    <garage href="/garage/0"/>
    <garage href="/garage/1"/>
    ...
    <form name="search" action="/garages" method="get">
        <input name="paint" type="string"/>
        <!-- other things to search for can go here -->
    </form>
</garages>

因此，流程是，当用户想要在多个车库中搜索汽车时，他们首先搜索这些车库并将他们感兴趣的车库添加到列表中（这只是 URL 列表）。然后，他们使用车库列表作为输入来搜索汽车。

在这种情况下，车库和汽车仅通过 URL 耦合。

您可以通过在车库集合中提供汽车搜索的链接来进一步扩展此功能。例如，假设我们搜索带有黄色油漆的车库，我们可能会得到像这样的集合

<garages self="/garages?paint=yellow">
    <garage href="/garage/24"/>
    <garage href="/garage/36"/>
    ...
</garages>

要获取此集合的汽车列表，我们可以添加一个链接，如下所示

<garages self="/garages?paint=yellow">
    <garage href="/garage/24"/>
    <garage href="/garage/36"/>
    <link rel="cars" href="/cars?garage=/garage/24,/garage/36"/>
</garages>

这适用于较小的列表或车库，但当车库列表增长时就会出现问题，在这种情况下，汽车的 URL 将变得太长。

相反，我们可以使用搜索的 URL 作为输入参数。例如，

<garages self="/garages?paint=yellow">
    <garage href="/garage/24"/>
    <garage href="/garage/36"/>
    <link rel="cars" href="/cars?garages=/garages?paint=yellow"/>
</garages>

在这种情况下，当您点击汽车链接时，您的服务将需要执行车库查询，检索每个车库的汽车列表，然后返回合并的汽车列表。除了较短的 URL 之外，此查询的好处是，当车库的油漆库存发生变化时，它始终会为您提供车库中涂有黄色油漆的汽车列表。

你们的服务如何获取车库的汽车列表？车库实体可以具有到汽车集合的链接。例如

<garage self="/garage/24">
    ... details about the garage ...
    <link rel="cars" href="/cars?garage=/garages/24"/>
</garages>

正如我在顶部所说，使用您自己的端点，但通过假设它们是您自己的端点来与它们紧密耦合。为您的实体构建超媒体控件，当您的服务需要使用它们时，像对待任何其他外部 API 一样对待它们。

最后（有点偏离主题），为了支持大量汽车和车库的集合，您可以向集合添加分页。例如

<garages self="/garages?page=2">
    <garage href="/garage/10"/>
    <garage href="/garage/11"/>
    ...
    <link rel="next" href="/garages?page=3"/>
    <link rel="prev" href="/garages"/>
</garages>

您甚至可能需要考虑让您的集合符合RFC5005 分页提要和完整提要，以便可以使用标准工具使用它们。

更新

下面是一个车库集合的示例，其中包含 JSON 格式的超媒体控件，使用了上面的一些概念：

{
    "self": "/garages?paint=yellow&page=2",
    "garages": [
        {
            "href": "/garage/24"
            //... summary properties for this garage go here ...
            //... you can even add a "media-types" array, to tell the service consumer
            //    what media types the garage is available in... 
        },
        {
            "href": "/garage/36"
        }
    ],
    "next": {
        "href": "/garages?paint=yellow"
    },
    "prev": {
        "href": "/garages?paint=yellow&page=3"
    },
    "cars": {
        "href": "/cars?garages=/garages?paint=yellow"
    },
    "search": {
        "href": "/garages?paint=yellow",
        "method": "GET",
        "inputs": {
            ... form input parameters go here ...
        }
    }
}