android - 根对象与否？ 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 进行仿真的。

我不赞成缺少根 key 会使响应更易于使用的论点。从嵌套一层的 JSON 对象中获取数据的工作量微不足道。

c) 根键是"data"

发布此问题时，JSON API specification尚未达到 v1.0，这意味着可能会发生重大变化。如果您现在查看他们的(稳定)规范，您会看到 their stance on the root key已经改变了。

The proposal for v1.0 Release Candidate 2 changed the top-level key to "data".

Primary resources MUST now appear under the top-level "data" key.

以这个单一资源为例

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

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