root对象还是没有？API响应的最佳做法是什么？

Question

JSON响应数据的最佳实践是什么,将对象嵌套在父对象中并包含根密钥路径？

{
    "activity": {
        "id": 20,
        "description": "a nice walk",
        "time_occurred": "2013-07-15T22:10:23Z",
        "duration": 45,
        "distance": 4.24,
        "location":"McDonalds"
    }
}

要么

{
    "id": 20,
    "description": "a nice walk",
    "time_occurred": "2013-07-15T22:10:23Z",
    "duration": 45,
    "distance": 4.24,
    "location":"McDonalds"
}

似乎大多数HTTP框架(RestKit,GSON等)可以处理任何一种情况,但我希望有一个明确的答案,哪种方法更好,为什么.我觉得第一种方法更具描述性,总是很好,但第二种方法更轻量级,你应该已经知道基于url路径映射到哪个对象.

注意:我要求具体参考移动应用后端.

Answer 1

a) 描述资源/集合的根键

这样做的好处是在响应中提供额外的上下文。根键描述资源或集合。我个人喜欢这种方法，因为响应文档所描述的内容很明显——您可能会认为从端点来看这是显而易见的，但情况并非总是如此。

b) 没有描述资源/集合的根密钥

这种方法在野外更为常见。需要高可用性和快速性的 API 通常会从响应文档中删除不必要的数据，以减少服务器负载和请求大小。这是其他人在设计自己的 API 时会考虑的典型流行 API，因此您会看到它是针对不在相同条件下运行的 API 进行模拟的。

我不相信缺少根密钥会使响应更容易使用的论点。从嵌套一层的 JSON 对象中获取数据的工作量微不足道。

c) 根密钥是"data"

当这个问题发布时，JSON API 规范尚未达到 v1.0，这意味着可能会发生重大更改。如果您现在查看他们的（稳定）规范，您会发现他们对根密钥的立场已经改变。

v1.0 候选版本 2 的提案将顶级密钥更改为"data".

主要资源现在必须出现在顶级"data"键下。

以这个单一资源为例

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "The best article of all time",
      "author": "Kanye West"
    }
 }

我找不到这背后的原因，但我怀疑这是因为一致性。无论何种资源，我们始终可以从文档响应中获取数据，因为顶级成员是一致的（假设 API 遵循 JSON API v1.0 规范）。

Answer 2

看起来双方都有牵引力。

有利于根元素

根据 JSONAPI.org

它的根密钥必须与服务器对集合的 GET 请求的响应中提供的根密钥相同。

例如，假设有以下照片采集请求：

GET /photos

HTTP/1.1 200 OK
Content-Type: application/json

{
  "photos": [{
    "id": "1",
    "title": "Mustaches on a Stick"
  }]
}

赞成无根元素

Twitter 在使用设置对象时不会

{
    "always_use_https": true, 
    "discoverable_by_email": true, 
    "geo_enabled": true, 
    "language": "en", 
    "protected": false, 
    "screen_name": "theSeanCook", 
    "show_all_inline_media": false, 
    "sleep_time": {
        "enabled": false, 
        "end_time": null, 
        "start_time": null
    }, 
    "time_zone": {
        "name": "Pacific Time (US & Canada)", 
        "tzinfo_name": "America/Los_Angeles", 
        "utc_offset": -28800
    }, 
    "trend_location": [
        {
            "country": "United States", 
            "countryCode": "US", 
            "name": "Atlanta", 
            "parentid": 23424977, 
            "placeType": {
                "code": 7, 
                "name": "Town"
            }, 
            "url": "http://where.yahooapis.com/v1/place/2357024", 
            "woeid": 2357024
        }
    ], 
    "use_cookie_personalization": true
}

Instagram 使用数据和元数据的组合，但不使用根用户对象

{
  "meta":  {
    "code": 200
  },
  "data":  {
    "username": "obama",
    "bio": "",
    "website": "",
    "profile_picture": "http://images.ak.instagram.com/profiles/anonymousUser.jpg",
    "full_name": "",
    "counts":  {
      "media": 30,
      "followed_by": 113,
      "follows": 130
    },
    "id": "2082346"
  }
}