返回资源的聚合数据

Question

假设您正在领导新 REST API 的开发。绿地。

并且您已经为您的 REST API 的人员提供了这个结构，这个架构：

{
   "id": 12,
   "name":{
          "first":"Angie",
          "last": "Smith",
          "middle": "joy",
          "maiden": "crowly",
    },
    "address": {
          "street": "1122 Something St.",
          ..and so on...
    },
... and so on
}

假设您有一个 API 客户（在这种情况下，是一个全新的 Web 团队，他们被聘用的远程且非常缺乏经验）来找您说“嘿，我需要一个包含所有唯一姓氏的列表系统”。

你愿意：

a) 告诉那个人“好的，当然，井名已经是我们人员资源端点的一部分。我们可以只返回一个人员列表，它会给你返回 name.last 字段，并且您只会为每个不同的 name.last 存在一个人”。基本上只是给他们一个聚合的人群分组，以满足他们对数据库中每个唯一姓氏的需求。

所以对于假设的 url 示例，他们只需调用 /people?fields=name.last?aggregate

b) 哦，好的，我们只会为您创建一个特殊的端点，我们还不知道该资源或端点 url 会是什么样子，但我们会给您这个：

{
     "lastNames": {
            "name": "Anderson",
            "name": "Alvertson",
         ....etc.
      }
}

谁知道这到底是什么资源，你连名字都没有。

而您忘记了 REST 的所有好处，因为您的客户拒绝理解您需要维护一个架构和约定，并且您通过您设置的资源向他们提供他们需要的东西，但他们认为他们必须遵守任何类型的规定很奇怪资源模板，并期望您构建无限/无尽的自定义资源，这些资源没有一致性，甚至无法命名这些资源，因为它们将您的 API 耦合到他们的应用程序，并且他们希望您遵守他们认为应该遵守的任何合同设计...意味着他们觉得他们可以从字面上告诉您如何设计您的 API，而您没有发言权！

而且您知道，如果您只放弃这一次并绕过您当前的 REST 资源，即“Person”，他们很可能希望您放弃您已经做出或想要使用 API 做出的任何设计决策因为你让他们说他们不关心你的设计，但你是平台团队，为全公司的消费创建这个 API！

而且您知道有一天您的 API 可能会被许多应用、其他服务甚至公众使用。

或

c) 就这么说吧，然后一起退出，因为压力不断地试图向他们解释 REST 以及为什么你试图保持某些约定，甚至是有意义的资源的简单想法和试图重用这些资源来获取相关数据，并找到一个更好的地方和团队一起工作，因为在建设性和巧妙地一次又一次地告诉他们我们有我们在 API、网络上坚持的约定之后团队仍然觉得他们需要 100% 决定你的 REST API 设计，他们对 REST 没有任何了解，所以他们不在乎你说什么......他们认为他们可以拥有 API，即使是你和他们平台团队为公司构建它不仅是为了他们的消费，还可能是为了其他应用程序、服务，甚至将来将此 API 公开给公共消费者。

Answer 1

根据我的经验，这是 REST（或任何其他）API 提供者与 Web、移动设备以及任何 API 使用者之间合作时最常见的问题。

我总是尽可能地遵守规则，并迫使消费者接受我的约定和架构。为什么？由于您提到的原因，其中一个至关重要：您的 API 可能有一天会公开，并且您不能让自己在每次消费者需要向用户展示粉红色裙子时都引入新的端点。

因此，a 对我来说很有意义，并提供了最 RESTful 的方法。

由于上述原因，

b 没有意义。请记住，在这类问题中，最困难的是引入第一个专用端点。完成后，下一个只是时间问题。

有时 c 对我来说很有意义，但我仍然尝试解释 ;)

请记住，在设计/实现 API 时，您必须与规则保持一致——即使您自己设置了规则。