使用 JSON API 表示非资源性聚合数据答案

【问题标题】：Representing non-resourceful aggregated data with JSON API使用 JSON API 表示非资源性聚合数据
【发布时间】：2016-04-27 20:56:40
【问题描述】：

我正在开发一个应用程序，我们正在研究使用 jsonapi 来描述所有 API 响应中的数据的可能性。它对于类似资源的实体非常有效，但是我们在想出一种以类似 jsonapi 的方式描述报告数据的方法时遇到了一些麻烦。

通过报告数据，我指的是从我们存储在数据库中的基本资源类数据动态聚合和计算的数据。例如，假设我们存储房地产信息，并且我们有关于房屋、公寓和办公空间的信息，每个信息都与位置、房产面积（以平方英尺为单位）、房产类型（无论是房子、公寓还是办公空间）相关联，以及有关财产的任何其他相关信息。现在假设我们需要一个接收?group_by[]=location&group_by[]=type 的报告，并且我们希望响应传达关于这两个group_by 参数交集的聚合信息。例如，我们会收到一个对象，该对象包含给定位置所有属性的平均平方英尺面积，也按属性类型分组。

Average Property Sizes (in square feet)
                Houses    Apartments   Offices
Manhattan      1234.56        234.56    123.45
Cape Coral      456.78        654.32    876.54
Portland       4321.00        987.65   2345.67

我们可以从这些数据中想到的最类似于资源的东西是每个单元格，但由于它们是更基本数据的计算聚合结果，因此它们没有自然 ID。我们一直在考虑为它们提供计算 ID（也许结合它们的数据分组的维度的 ID，即"house,34"，其中house 代表一种属性，34 是 ID地点“曼哈顿”）。然后每个单元格将与相应的位置记录有关系，该位置记录将包含在有效负载的included 部分中。这是一个示例 json 文件，它的外观如下：

{
  "data": [
    {
      "id": "house,123",
      "type": "report_items",
      "attributes": {
        "property_type": "house",
        "value": 108.75
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 123
          }
        }
      }
    },
    {
      "id": "house,124",
      "type": "report_items",
      "attributes": {
        "property_type": "house",
        "value": 36.0
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 124
          }
        }
      }
    },
    {
      "id": "house,125",
      "type": "report_items",
      "attributes": {
        "property_type": "house",
        "value": 1.0
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 125
          }
        }
      }
    },
    {
      "id": "office,123",
      "type": "report_items",
      "attributes": {
        "property_type": "office",
        "value": 4.0
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 123
          }
        }
      }
    },
    {
      "id": "office,124",
      "type": "report_items",
      "attributes": {
        "property_type": "office",
        "value": 2.0
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 124
          }
        }
      }
    },
    {
      "id": "apartment,123",
      "type": "report_items",
      "attributes": {
        "property_type": "apartment",
        "value": 2.0
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 123
          }
        }
      }
    },
    {
      "id": "apartment,125",
      "type": "report_items",
      "attributes": {
        "property_type": "apartment",
        "value": 4.5
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 125
          }
        }
      }
    },
    {
      "id": "apartment,124",
      "type": "report_items",
      "attributes": {
        "property_type": "apartment",
        "value": 2.0
      },
      "relationships": {
        "location": {
          "data": {
            "type": "locations",
            "id": 124
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "locations",
      "id": "123",
      "attributes": {
        "name": "Manhattan"
      }
    },
    {
      "type": "locations",
      "id": "124",
      "attributes": {
        "name": "Cape Coral"
      }
    },
    {
      "type": "locations",
      "id": "125",
      "attributes": {
        "name": "Portland"
      }
    }
  ]
}

我的问题是：这是在 jsonapi 中表示此类数据的正确方法吗？ jsonapi 是否适合和/或推荐用于不直接映射到资源的数据？在自定义 json 中表示这些数据会更好吗？我知道这些问题中没有一个可能有明确的答案，但也许已经有一些关于如何处理类似场景的经验，尝试使这种数据适合 jsonapi 等的利弊等。任何 cmets 和帮助都非常非常感激。谢谢。

PS：即使在论坛和互联网上进行了一些挖掘之后，我还是发布了这个，这是我发现的仅有的两个链接，它们谈论的东西类似于我试图找出的东西，我将它们包括在这里也可供参考： 1.- http://discuss.jsonapi.org/t/composite-id-inside-the-resource-object/367/13 2.- http://discuss.jsonapi.org/t/extension-for-chart-graph-data/408

【问题讨论】：

我并不是要针对这种特殊情况提供特定的解决方案，而是要提供一些有关将 JSON API 用于此类非资源性数据的可能性的信息。推荐吗？我应该付出额外的努力来尝试使我的数据适应 JSON API 吗？或者 JSON API 可能被设计为专门用于类似资源的数据？

标签： json rest api-design json-api

【解决方案1】：

一般的答案是考虑哪些数据足够重要以保证 API 双方的身份。我的意思是决定你以后要参考哪些东西，或者用关系来代表哪些东西。 JSON API 允许您将这些东西定义为资源，并允许您将资源与更通用的 JSON 混合用于不透明的数据。

例如，也许reports 以及您用来创建它们的选项和过滤器值得跟踪，以便客户可以通过其id 请求重新查看同一报告。也许您想轮询您的服务器以查看正在创建哪些报告。

在客户端，您可能希望提供来自 property_type 资源的链接，以获取有关这些属性类型的更多信息。

或者，报告中的结果可能更好地表示为资源中的 JSON 块。 attributes 和 meta 可以包含任何类型的 JSON 值。

在您的特定情况下，您的主要资源可能是 reports 类型，或 report_items 的数组，甚至可能是与 property_types 和 locations 有关系的 property_summaries 数组。

如果您选择更通用的资源类型，您可以概括报告过程，但您可能无法捕捉到数据的重要性。

如果您选择非常具体的资源进行报告，则需要真正自定义每种类型的报告，但您将能够在客户端上的资源之间建立有意义的联系。

【讨论】：