php - API应该消耗自己还是直接调用数据库获取其他资源？

Question

This question is an extension although separate of this question posted earlier.

所以我们有一个车库有多辆车的基本示例，所以我们的端点是

/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

使用您自己的端点(这称为 service layering 并且有很多好处)，但不要与您的端点紧密耦合。

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

使用hypermedia controls (即链接和表单)在汽车列表中添加搜索表单。假设您的汽车列表看起来像(为简洁起见排除了方案和主机)

<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，则可以执行此查询而根本不需要查询车库，并且如上所述支持在完全不同的系统中拥有车库，假设其他系统使用您的 media-type或者您支持他们的媒体类型。

显然，您在搜索时需要访问车库 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 Paged Feeds和 Complete Feeds , 因此可以使用标准工具使用它们。

更新

这是一个带有 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 ...
        }
    }
}