使用JSON API

时间:2016-04-18 21:26:12

标签: json rest api-design json-api

我正在研究一个应用程序,我们正在研究使用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 1}}是“曼哈顿”的位置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等的利弊。任何评论和帮助是非常的非常感激。感谢。

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

1 个答案:

答案 0 :(得分:3)

一般的答案是考虑哪些数据足够重要,以保证API双方的身份。通过这个我的意思是决定你想要在以后引用哪些事情或用关系来表示。 JSON API允许您将这些内容定义为资源,并允许您将资源与更通用的JSON混合用于不透明的数据。

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

在客户端,您可能希望将property_type资源中的链接提供给有关这些属性类型的更多信息。

或者,报告中的结果可能更好地表示为资源中的一个JSON blob。 attributesmeta可以包含任何类型的JSON值。

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

如果您选择更多通用类型的资源,则可以概括报告流程,但您可能无法捕获数据的重要性。

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