顶级保留属性名称

顶级的JSON对象可能包含下面这些属性

apiVersion

属性值类型: 字符串(string)
父节点: -

呈现请求中服务API期望的版本，以及在响应中保存的服务API版本。应随时提供apiVersion。这与数据的版本无关。将数据版本化应该通过其他的机制来处理，如etag。

示例：

{ "apiVersion": "2.1" }

context

属性值类型: 字符串(string)
父节点: -

客户端设置这个值，服务器通过数据作出回应。这在JSON-P和批处理中很有用，用户可以使用context将响应与请求关联起来。该属性是顶级属性，因为不管响应是成功还是有错误，context总应当被呈现出来。context不同于id在于context由用户提供而id由服务分配。

示例：

请求 #1:

http://www.google.com/myapi?context=bart

请求 #2:

http://www.google.com/myapi?context=lisa

响应 #1:

{
  "context": "bart",
  "data": {
    "items": []
  }
}

响应 #2:

{
  "context": "lisa",
  "data": {
    "items": []
  }
}

公共的JavaScript处理器通过编码同时处理以下两个响应：

function handleResponse(response) {
  if (response.result.context == "bart") {
    // 更新页面中的 "Bart" 部分。
  } else if (response.result.context == "lisa") {
    // 更新页面中的 "Lisa" 部分。
  }
}

id

属性值类型: 字符串(string)
父节点: -

服务提供用于识别响应的标识(无论请求是成功还是有错误)。这对于将服务日志和单独收到的响应对应起来很有用。

示例：

{ "id": "1" }

method

属性值类型: 字符串(string)
父节点: -

表示对数据即将执行，或已被执行的操作。在JSON请求的情况下，method属性可以用来指明对数据进行何种操作。在JSON响应的情况下，method属性表明对数据进行了何种操作。

一个JSON-RPC请求的例子，其中method属性表示要在params上执行的操作：

{
  "method": "people.get",
  "params": {
    "userId": "@me",
    "groupId": "@self"
  }
}

params

属性值类型: 对象(object)
父节点: -

这个对象作为输入参数的映射发送给RPC请求。它可以和method属性一起用来执行RPC功能。若RPC方法不需要参数，则可以省略该属性。

示例：

{
  "method": "people.get",
  "params": {
    "userId": "@me",
    "groupId": "@self"
  }
}

data

属性值类型: 对象(object)
父节点: -

包含响应的所有数据。该属性本身拥有许多保留属性名，下面会有相应的说明。服务可以自由地将自己的数据添加到这个对象。一个JSON响应要么应当包含一个data对象，要么应当包含error对象，但不能两者都包含。如果data和error同时出现，则error对象优先。

error

属性值类型: 对象(object)
父节点: -

表明错误发生，提供错误的详细信息。错误的格式支持从服务返回一个或多个错误。一个JSON响应可以有一个data对象或者一个error对象，但不能两者都包含。如果data和error都出现，error对象优先。

示例：

{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found
    }]
  }
}