JSON風格指南
JSON風格指南
版本：0.9
英文版：
翻譯：Darcy Liu
譯文狀态：草稿
簡介
該風格指南是對(duì)在Google創建JSON APIs而提供的指導性準則和建議。總體來講，JSON APIs應遵循JSON.org上的規範。這(zhè)份風格指南澄清和标準化了特定情況，從而使Google的JSON APIs有一種(zhǒng)标準的外觀和感覺。這(zhè)些指南适用于基于RPC和基于REST風格的API的JSON請求和響應。
定義
爲了更好(hǎo)地實現這(zhè)份風格指南的目的，下面(miàn)幾項需要說(shuō)明：
- 屬性(property) - JSON對(duì)象内的鍵值對(duì)(name/value pair)
- 屬性名(property name) - 屬性的名稱(或鍵)
- 屬性值(property value) - 分配給屬性的值
示例：
{
// 一組鍵值對(duì)稱作一個 "屬性".
"propertyName": "propertyValue"
}
Javascript的數字(number)包含所有的浮點數,這(zhè)是一個寬泛的指定。在這(zhè)份指南中，數字(number)指代Javascript中的數字(number)類型，而整型(integer)則指代整型。
一般準則
注釋
JSON對(duì)象中不包含注釋。
JSON對(duì)象中不應該包含注釋。該指南中的某些示例含有注釋。但這(zhè)僅僅是爲了說(shuō)明示例。
{
// 你可能(néng)在下面(miàn)的示例中看到注釋,
// 但不要在你的JSON數據中加入注釋.
"propertyName": "propertyValue"
}
雙引号
使用雙引号
如果（某個）屬性需要引号，則必須使用雙引号。所有的屬性名必須在雙引号内。字符類型的屬性值必須使用雙引号。其它類型值（如布爾或數字）不應該使用雙引号。
扁平化數據 VS 結構層次
不能(néng)爲了方便而將(jiāng)數據任意分組
JSON中的數據元素應以扁平化方式呈現。不能(néng)爲了方便而將(jiāng)數據任意分組。
在某些情況下，比如描述單一結構的一批屬性，因爲它被(bèi)用來保持結構層次，因而是有意義的。但是遇到這(zhè)些情況還(hái)是應當慎重考慮，記住隻有語義上有意義的時(shí)候才使用它。例如，一個地址可以有表示兩(liǎng)種(zhǒng)方式，但結構化的方式對(duì)開(kāi)發(fā)人員來講可能(néng)更有意義：
扁平化地址:
{
"company": "Google",
"website": "http://www.google.com/",
"addressLine1": "111 8th Ave",
"addressLine2": "4th Floor",
"state": "NY",
"city": "New York",
"zip": "10011"
}
結構化地址：
{
"company": "Google",
"website": "http://www.google.com/",
"address": {
"line1": "111 8th Ave",
"line2": "4th Floor",
"state": "NY",
"city": "New York",
"zip": "10011"
}
}
屬性名準則
屬性名格式
選擇有意義的屬性名
屬性名必須遵循以下準則:
- 屬性名應該是具有定義語義的有意義的名稱。
- 屬性名必須是駝峰式的，ASCII碼字符串。
- 首字符必須式字母，下劃線(_)或美元符号($)。
- 随後(hòu)的其他字符可以是字母，數字，下劃線(_)或美元符号($)。
- 應該避免使用Javascript中的保留關鍵字(下文附有Javascript保留字清單)
這(zhè)些準則反映JavaScript标識符命名的指導方針。使JavaScript的客戶端可以使用點符号來訪問屬性。(例如,result.thisIsAnInstanceVariable).
下面(miàn)是一個對(duì)象的一個屬性的例子：
{
"thisPropertyIsAnIdentifier": "identifier value"
}
JSON Map中的鍵名
在JSON Map中鍵名可以使用任意Unicode字符
當JSON對(duì)象作爲Map(映射)使用時(shí)，屬性的名稱命名規則并不适用。Map（也稱作關聯數組）是一個具有任意鍵/值對(duì)的數據類型，這(zhè)些鍵/值對(duì)通過(guò)特定的鍵來訪問相應的值。JSON對(duì)象和JSON Map在運行時(shí)看起(qǐ)來是一樣(yàng)的；這(zhè)個特性與API設計相關。當JSON對(duì)象被(bèi)當作map使用時(shí)，API文件應當做出說(shuō)明。
Map的鍵名不一定要遵循屬性名稱的命名準則。鍵名可以包含任意的Unicode字符。客戶端可使用maps熟悉的方括号來訪問這(zhè)些屬性。（例如result.thumbnails["72"]）
{
// "address" 屬性是一個子對(duì)象
// 包含地址的各部分.
"address": {
"addressLine1": "123 Anystreet",
"city": "Anytown",
"state": "XX",
"zip": "00000"
},
// "address" 是一個映射
// 含有響應規格所對(duì)應的URL，用來映射thumbnail url的像素規格
"thumbnails": {
"72": "http://url.to.72px.thumbnail",
"144": "http://url.to.144px.thumbnail"
}
}
保留的屬性名稱
某些屬性名稱會(huì)被(bèi)保留以便能(néng)在多個服務間相容使用
保留屬性名稱的詳細信息，連同完整的列表，可在本指南後(hòu)面(miàn)的内容中找到。服務應按照被(bèi)定義的語義來使用屬性名稱。
單數屬性名 VS 複數屬性名
數組類型應該是複數屬性名。其它屬性名都(dōu)應該是單數。
數組通常包含多個條目，複數屬性名就(jiù)反映了這(zhè)點。在下面(miàn)這(zhè)個保留名稱中可以看到例子。屬性名items是複數因爲它描述的是一組對(duì)象。大多數的其它字段是單數。
當然也有例外，尤其是涉及到數字的屬性值的時(shí)候。例如，在保留屬性名中，totalItems 比 totalItem更合理。然後(hòu)，從技術上講，這(zhè)并不違反風格指南，因爲 totalItems 可以被(bèi)看作 totalOfItems, 其中 total 是單數（依照風格指南），OfItems 用來限定總數。字段名也可被(bèi)改爲 itemCount，這(zhè)樣(yàng)看起(qǐ)來更象單數.
{
// 單數
"author": "lisa",
// 一組同胞, 複數
"siblings": [ "bart", "maggie"],
// "totalItem" 看起(qǐ)來并不對(duì)
"totalItems": 10,
// 但 "itemCount" 要好(hǎo)些
"itemCount": 10,
}
命名沖突
通過(guò)選擇新的屬性名或將(jiāng)API版本化來避免命名沖突
新的屬性可在將(jiāng)來被(bèi)添加進(jìn)保留列表中。JSON中不存在命名空間。如果存在命名沖突，可通過(guò)選擇新的屬性名或者版本化來解決這(zhè)個問題。例如，假設我們由下面(miàn)的JSON對(duì)象開(kāi)始：
{
"apiVersion": "1.0",
"data": {
"recipeName": "pizza",
"ingredients": ["tomatoes", "cheese", "sausage"]
}
}
如果我們希望將(jiāng)來把ingredients列爲保留字，我們可以通過(guò)下面(miàn)兩(liǎng)件事(shì)情來達成(chéng)。 1.選一個不同的名字
{
"apiVersion": "1.0",
"data": {
"recipeName": "pizza",
"ingredientsData": "Some new property",
"ingredients": ["tomatoes", "cheese", "sausage"]
}
}
2.在主版本上重新命名屬性
{
"apiVersion": "2.0",
"data": {
"recipeName": "pizza",
"ingredients": "Some new property",
"recipeIngredients": ["tomatos", "cheese", "sausage"]
}
}
屬性值準則
屬性值格式
屬性值必須是Unicode 的 booleans（布爾）, 數字(numbers), 字符串(strings), 對(duì)象(objects), 數組(arrays), 或 null.
JSON.org上的标準準确的說(shuō)明了哪些類型的數據可以作爲屬性值。這(zhè)包含Unicode的布爾(booleans), 數字(numbers), 字符串(strings), 對(duì)象(objects), 數組(arrays), 或 null。JavaScript表達式是不被(bèi)接受的。APIs應該支持該準則，并爲某個特定的屬性選擇最合适的數據類型（比如，用numbers代表numbers等）。
好(hǎo)的例子：
{
"canPigsFly": null, // null
"areWeThereYet": false, // boolean
"answerToLife": 42, // number
"name": "Bart", // string
"moreData": {}, // object
"things": [] // array
}
不好(hǎo)的例子：
{
"aVariableName": aVariableName, // Bad - JavaScript 标識符
"functionFoo": function() { return 1; } // Bad - JavaScript 函數
}
空或Null 屬性值
考慮移除空或null值
如果一個屬性是可選的或者包含空值或null值，考慮從JSON中去掉該屬性，除非它的存在有很強的語義原因。
{
"volume": 10,
// 即使 "balance" 屬性值是零, 它也應當被(bèi)保留,
// 因爲 "0" 表示 "均衡"
// "-1" 表示左傾斜和"＋1" 表示右傾斜
"balance": 0,
// "currentlyPlaying" 是null的時(shí)候可被(bèi)移除
// "currentlyPlaying": null
}
枚舉值
枚舉值應當以字符串的形式呈現
随著(zhe)APIs的發(fā)展，枚舉值可能(néng)被(bèi)添加，移除或者改變。將(jiāng)枚舉值當作字符串可以使下遊用戶幽雅的處理枚舉值的變更。
Java代碼：
public enum Color {
WHITE,
BLACK,
RED,
YELLOW,
BLUE
}
JSON對(duì)象：
{
"color": "WHITE"
}
屬性值數據類型
上面(miàn)提到，屬性值必須是布爾(booleans), 數字(numbers), 字符串(strings), 對(duì)象(objects), 數組(arrays), 或 null. 然而在處理某些值時(shí)，定義一組标準的數據類型是非常有用的。這(zhè)些數據類型必須始終是字符串，但是爲了便于解析，它們也會(huì)以特定的方式被(bèi)格式化。
日期屬性值
日期應該使用RFC3339建議的格式
日期應該是RFC 3339所建議的字符串格式。
{
"lastUpdate": "2007-11-06T16:34:41.000Z"
}
時(shí)間間隔屬性值
時(shí)間間隔應該使用ISO 8601建議的格式
時(shí)間間隔應該是ISO 8601所建議的字符串格式。
{
// 三年, 6個月, 4天, 12小時(shí),
// 三十分鍾, 5秒
"duration": "P3Y6M4DT12H30M5S"
}
緯度/經(jīng)度屬性值
緯度/經(jīng)度應該使用ISO 6709建議的格式
緯度/經(jīng)度應該是ISO 6709所建議的字符串格式。 而且, 它應該更偏好(hǎo)使用 e ±DD.DDDD±DDD.DDDD 角度格式.
{
// 自由女神像的緯度/經(jīng)度位置.
"statueOfLiberty": "+40.6894-074.0447"
}
JSON結構和保留屬性名
爲了使APIs保持一緻的借口，JSON對(duì)象應當使用以下的結構。該結構适用于JSON的請求和響應。在這(zhè)個結構中，某些屬性名將(jiāng)被(bèi)保留用作特殊用途。這(zhè)些屬性并不是必需的，也就(jiù)是說(shuō)，每個保留的屬性可能(néng)出現零次或一次。但是如果服務需要這(zhè)些屬性，建議遵循該命名條約。下面(miàn)是一份JSON結構語義表，以Orderly格式呈現(現在已經(jīng)被(bèi)納入 JSONSchema)。你可以在該指南的最後(hòu)找到關于JSON結構的例子。
object {
string apiVersion?;
string context?;
string id?;
string method?;
object {
string id?
}* params?;
object {
string kind?;
string fields?;
string etag?;
string id?;
string lang?;
string updated?; # date formatted RFC 3339
boolean deleted?;
integer currentItemCount?;
integer itemsPerPage?;
integer startIndex?;
integer totalItems?;
integer pageIndex?;
integer totalPages?;
string pageLinkTemplate /^https?:/ ?;
object {}* next?;
string nextLink?;
object {}* previous?;
string previousLink?;
object {}* self?;
string selfLink?;
object {}* edit?;
string editLink?;
array [
object {}*;
] items?;
}* data?;
object {
integer code?;
string message?;
array [
object {
string domain?;
string reason?;
string message?;
string location?;
string locationType?;
string extendedHelp?;
string sendReport?;
}*;
] errors?;
}* error?;
}*;
JSON對(duì)象有一些頂級屬性，然後(hòu)是data對(duì)象或error對(duì)象，這(zhè)兩(liǎng)者不會(huì)同時(shí)出現。下面(miàn)是這(zhè)些屬性的解釋。
頂級保留屬性名稱
頂級的JSON對(duì)象可能(néng)包含下面(miàn)這(zhè)些屬性
apiVersion
屬性值類型: 字符串(string)
父節點: -
呈現請求中服務API期望的版本，以及在響應中保存的服務API版本。應随時(shí)提供apiVersion。這(zhè)與數據的版本無關。將(jiāng)數據版本化應該通過(guò)其他的機制來處理，如etag。
示例：
{ "apiVersion": "2.1" }
context
屬性值類型: 字符串(string)
父節點: -
客戶端設置這(zhè)個值，服務器通過(guò)數據作出回應。這(zhè)在JSON-P和批處理中很有用，用戶可以使用context將(jiāng)響應與請求關聯起(qǐ)來。該屬性是頂級屬性，因爲不管響應是成(chéng)功還(hái)是有錯誤，context總應當被(bèi)呈現出來。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處理器通過(guò)編碼同時(shí)處理以下兩(liǎng)個響應：
function handleResponse(response) {
if (response.result.context == "bart") {
// 更新頁面(miàn)中的 "Bart" 部分。
} else if (response.result.context == "lisa") {
// 更新頁面(miàn)中的 "Lisa" 部分。
}
}
id
屬性值類型: 字符串(string)
父節點: -
服務提供用于識别響應的标識(無論請求是成(chéng)功還(hái)是有錯誤)。這(zhè)對(duì)于將(jiāng)服務日志和單獨收到的響應對(duì)應起(qǐ)來很有用。
示例：
{ "id": "1" }
method
屬性值類型: 字符串(string)
父節點: -
表示對(duì)數據即將(jiāng)執行，或已被(bèi)執行的操作。在JSON請求的情況下，method屬性可以用來指明對(duì)數據進(jìn)行何種(zhǒng)操作。在JSON響應的情況下，method屬性表明對(duì)數據進(jìn)行了何種(zhǒng)操作。
一個JSON-RPC請求的例子，其中method屬性表示要在params上執行的操作：
{
"method": "people.get",
"params": {
"userId": "@me",
"groupId": "@self"
}
}
params
屬性值類型: 對(duì)象(object)
父節點: -
這(zhè)個對(duì)象作爲輸入參數的映射發(fā)送給RPC請求。它可以和method屬性一起(qǐ)用來執行RPC功能(néng)。若RPC方法不需要參數，則可以省略該屬性。
示例：
{
"method": "people.get",
"params": {
"userId": "@me",
"groupId": "@self"
}
}
data
屬性值類型: 對(duì)象(object)
父節點: -
包含響應的所有數據。該屬性本身擁有許多保留屬性名，下面(miàn)會(huì)有相應的說(shuō)明。服務可以自由地將(jiāng)自己的數據添加到這(zhè)個對(duì)象。一個JSON響應要麼(me)應當包含一個data對(duì)象，要麼(me)應當包含error對(duì)象，但不能(néng)兩(liǎng)者都(dōu)包含。如果data和error同時(shí)出現，則error對(duì)象優先。
error
屬性值類型: 對(duì)象(object)
父節點: -
表明錯誤發(fā)生，提供錯誤的詳細信息。錯誤的格式支持從服務返回一個或多個錯誤。一個JSON響應可以有一個data對(duì)象或者一個error對(duì)象，但不能(néng)兩(liǎng)者都(dōu)包含。如果data和error都(dōu)出現，error對(duì)象優先。
示例：
{
"apiVersion": "2.0",
"error": {
"code": 404,
"message": "File Not Found",
"errors": [{
"domain": "Calendar",
"reason": "ResourceNotFoundException",
"message": "File Not Found
}]
}
}
data對(duì)象的保留屬性名
JSON對(duì)象的data屬性可能(néng)包含以下屬性。
data.kind
屬性值類型: 字符串(sting)
父節點: data
kind屬性是對(duì)某個特定的對(duì)象存儲何種(zhǒng)類型的信息的指南。可以把它放在data層次，或items的層次，或其它任何有助于區分各類對(duì)象的對(duì)象中。如果kind對(duì)象被(bèi)提供，它應該是對(duì)象的第一個屬性（詳見下面(miàn)的屬性順序部分）。
示例：
// "Kind" indicates an "album" in the Picasa API.
{"data": {"kind": "album"}}
data.fields
屬性值類型: 字符串(string)
父節點: data
表示做了部分GET之後(hòu)響應中出現的字段，或做了部分PATCH之後(hòu)出現在請求中的字段。該屬性僅在做了部分GET請求/批處理時(shí)存在，且不能(néng)爲空。
示例：
{
"data": {
"kind": "user",
"fields": "author,id",
"id": "bart",
"author": "Bart"
}
}
data.etag
屬性值類型: 字符串(string)
父節點: data
響應時(shí)提供etag。關于GData APIs中的ETags詳情可以在這(zhè)裡(lǐ)找到：http://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning
示例：
{"data": {"etag": "W/"C0QBRXcycSp7ImA9WxRVFUk.""}}
data.id
屬性值類型: 字符串(string)
父節點: data
一個全局唯一标識符用于引用該對(duì)象。id屬性的具體細節都(dōu)留給了服務。
示例：
{"data": {"id": "12345"}}
data.lang
屬性值類型: 字符串(string)(格式由BCP 47指定)
父節點: data (或任何子元素)
表示該對(duì)象内其他屬性的語言。該屬性模拟HTML的lang屬性和XML的xml:lang屬性。值應該時(shí)BCP 47中定義的一種(zhǒng)語言值。如果一個單一的JSON對(duì)象包含的數據有多種(zhǒng)語言，服務負責制定和标明的lang屬性的适當位置。
示例：
{"data": {
"items": [
{ "lang": "en",
"title": "Hello world!" },
{ "lang": "fr",
"title": "Bonjour monde!" }
]}
}
data.updated
屬性值類型: 字符串(string)(格式由RFC 3339指定)
父節點: data
指明條目更新的最後(hòu)日期/時(shí)間(RFC 3339)，由服務規定。
示例：
{"data": {"updated": "2007-11-06T16:34:41.000Z"}}
data.deleted
屬性值類型: 布爾(boolean)
父節點: data (或任何子元素)
一個标記元素，當出現時(shí)，表示包含的條目已被(bèi)删除。如果提供了删除屬性，它的值必須爲true;爲false會(huì)導緻混亂，應該避免。
示例：
{"data": {
"items": [
{ "title": "A deleted entry",
"deleted": true
}
]}
}
data.items
屬性值類型: 數組(array)
父節點: data
屬性名items被(bèi)保留用作表示一組條目(例如,Picasa中的圖片，YouTube中的視頻)。這(zhè)種(zhǒng)結構的目的是給與當前結果相關的集合提供一個标準位置。例如，知道(dào)頁面(miàn)上的items是數組，JSON輸出便可能(néng)插入一個通用的分頁系統。如果items存在，它應該是data對(duì)象的最後(hòu)一個屬性。（詳見下面(miàn)的屬性順序部分）。
示例：
{
"data": {
"items": [
{ /* Object #1 */ },
{ /* Object #2 */ },
...
]
}
}
用于分頁的保留屬性名
下面(miàn)的屬性位于data對(duì)象中，用來給一列數據分頁。一些語言和概念是從OpenSearch規範中借鑒過(guò)來的。
下面(miàn)的分頁數據允許各種(zhǒng)風格的分頁，包括：
- 上一頁/下一頁 - 允許用戶在列表中前進(jìn)和後(hòu)退，一次一頁。nextLink 和previousLink屬性 (下面(miàn)的"鏈接保留屬性名"部分有描述) 用于這(zhè)種(zhǒng)風格的分頁。
- 基于索引的分頁 - 允許用戶直接跳到條目列表的某個條目位置。例如，要從第200個條目開(kāi)始載入10個新的條目，開(kāi)發(fā)者可以給用戶提供一個URL的查詢字符串?startIndex=200。
- 基于頁面(miàn)的分頁 - 允許用戶直接跳到條目内的具體頁。這(zhè)跟基于索引的分頁很類似,但節省了開(kāi)發(fā)者額外的步驟，不需再爲新一頁的條目計算條目索引。例如，開(kāi)發(fā)人員可以直接跳到第20頁，而不是跳到第200條條目。基于頁面(miàn)分頁的網址，可以使用查詢字符串?page=1或?page=20。pageIndex和 totalPages 屬性用作這(zhè)種(zhǒng)風格的分頁.
在這(zhè)份指南的最後(hòu)可以找到如何使用這(zhè)些屬性來實現分頁的例子。
data.currentItemCount
屬性值類型: 整數(integer)
父節點: data
結果集中的條目數目。應該與items.length相等，并作爲一個便利屬性提供。例如，假設開(kāi)發(fā)者請求一組搜索條目，并且要求每頁10條。查詢集共有14條。第一個條目頁將(jiāng)會(huì)有10個條目，因此itemsPerPage和currentItemCount都(dōu)應該等于10。下一頁的條目還(hái)剩下4條；itemsPerPage仍然是10,但是currentItemCount是4.
示例：
{
"data": {
// "itemsPerPage" 不需要與 "currentItemCount" 匹配
"itemsPerPage": 10,
"currentItemCount": 4
}
}
data.itemsPerPage
屬性值類型: 整數(integer)
父節點: data
items結果的數目。未必是data.items數組的大小；如果我們查看的是最後(hòu)一頁，data.items的大小可能(néng)小于itemsPerPage。但是，data.items的大小不應超過(guò)itemsPerPage。
示例：
{
"data": {
"itemsPerPage": 10
}
}
data.startIndex
屬性值類型: 整數(integer)
父節點: data
data.items中第一個條目的索引。爲了一緻，startIndex應從1開(kāi)始。例如，第一組items中第一條的startIndex應該是1。如果用戶請求下一組數據，startIndex可能(néng)是10。
示例：
{
"data": {
"startIndex": 1
}
}
data.totalItemsx
屬性值類型: 整數(integer)
父節點: data
當前集合中可用的總條目數。例如，如果用戶有100篇博客文章，響應可能(néng)隻包含10篇，但是totalItems應該是100。
示例：
{
"data": {
"totalItems": 100
}
}
data.pagingLinkTemplate
屬性值類型: 字符串(string)
父節點: data
URL模闆指出用戶可以如何計算随後(hòu)的分頁鏈接。URL模闆中也包含一些保留變量名：表示要載入的條目的{index}，和要載入的頁面(miàn)的{pageIndex}。
示例：
{
"data": {
"pagingLinkTemplate": "http://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N"
}
}
data.pageIndex
屬性值類型: 整數(integer)
父節點: data
條目的當前頁索引。爲了一緻，pageIndex應從1開(kāi)始。例如，第一頁的pageIndex是1。pageIndex也可以通過(guò)基于條目的分頁而計算出來pageIndex = floor(startIndex / itemsPerPage) + 1。
示例：
{
"data": {
"pageIndex": 1
}
}
data.totalPages
屬性值類型: 整數(integer)
父節點: data
當前結果集中的總頁數。totalPages也可以通過(guò)上面(miàn)基于條目的分頁屬性計算出來: totalPages = ceiling(totalItems / itemsPerPage).。
示例：
{
"data": {
"totalPages": 50
}
}
用于鏈接的保留屬性名
下面(miàn)的屬性位于data對(duì)象中，用來表示對(duì)其他資源的引用。有兩(liǎng)種(zhǒng)形式的鏈接屬性：1）對(duì)象，它可以包含任何種(zhǒng)類的引用（比如JSON-RPC對(duì)象），2)URL字符串，表示資源的URIs(後(hòu)綴總爲'Link')。
data.self / data.selfLink
屬性值類型: 對(duì)象(object)/字符串(string)
父節點: data
自身鏈接可以用于取回條目數據。比如，在用戶的Picasa相冊中，條目中的每個相冊對(duì)象都(dōu)會(huì)包含一個selfLink用于檢索這(zhè)個相冊的相關數據。
示例：
{
"data": {
"self": { },
"selfLink": "http://www.google.com/feeds/album/1234"
}
}
data.edit / data.editLink
屬性值類型: 對(duì)象(object)/字符串(string)
父節點: data
編輯鏈接表明用戶可以發(fā)送更新或删除請求。這(zhè)對(duì)于REST風格的APIs很有用。該鏈接僅在用戶能(néng)夠更新和删除該條目時(shí)提供。
示例：
{
"data": {
"edit": { },
"editLink": "http://www.google.com/feeds/album/1234/edit"
}
}
data.next / data.nextLink
屬性值類型: 對(duì)象(object)/字符串(string)
父節點: data
該下一頁鏈接标明如何取得更多數據。它指明載入下一組數據的位置。它可以同itemsPerPage，startIndex 和 totalItems屬性一起(qǐ)使用用于分頁數據。
示例：
{
"data": {
"next": { },
"nextLink": "http://www.google.com/feeds/album/1234/next"
}
}
data.previous / data.previousLink
屬性值類型: 對(duì)象(object)/字符串(string)
父節點: data
該上一頁鏈接标明如何取得更多數據。它指明載入上一組數據的位置。它可以連同itemsPerPage，startIndex 和 totalItems屬性用于分頁數據。
示例：
{
"data": {
"previous": { },
"previousLink": "http://www.google.com/feeds/album/1234/next"
}
}
錯誤對(duì)象中的保留屬性名
JSON對(duì)象的error屬性應包含以下屬性。
error.code
屬性值類型: 整數(integer)
父節點: error
表示該錯誤的編号。這(zhè)個屬性通常表示HTTP響應碼。如果存在多個錯誤，code應爲第一個出錯的錯誤碼。
示例：
{
"error":{
"code": 404
}
}
error.message
屬性值類型: 字符串(string)
父節點: error
一個人類可讀的信息，提供有關錯誤的詳細信息。如果存在多個錯誤，message應爲第一個錯誤的錯誤信息。
示例：
{
"error":{
"message": "File Not Found"
}
}
error.errors
屬性值類型: 數組(array)
父節點: error
包含關于錯誤的附加信息。如果服務返回多個錯誤。errors數組中的每個元素表示一個不同的錯誤。
示例：
{ "error": { "errors": [] } }
error.errors[].domain
屬性值類型: 字符串(string)
父節點: error.errors
服務抛出該錯誤的唯一識别符。它幫助區分服務的從普通協議錯誤(如,找不到文件)中區分出具體錯誤(例如，給日曆插入事(shì)件的錯誤)。
示例：
{
"error":{
"errors": [{"domain": "Calendar"}]
}
}
error.errors[].reason
屬性值類型: 字符串(string)
父節點: error.errors
該錯誤的唯一識别符。不同于error.code屬性，它不是HTTP響應碼。
示例：
{
"error":{
"errors": [{"reason": "ResourceNotFoundException"}]
}
}
error.errors[].message
屬性值類型: 字符串(string)
父節點: error.errors
一個人類可讀的信息，提供有關錯誤的更多細節。如果隻有一個錯誤，該字段應該與error.message匹配。
示例：
{
"error":{
"code": 404
"message": "File Not Found",
"errors": [{"message": "File Not Found"}]
}
}
error.errors[].location
屬性值類型: 字符串(string)
父節點: error.errors
錯誤發(fā)生的位置（根據locationType字段解釋該值）。
示例：
{
"error":{
"errors": [{"location": ""}]
}
}
error.errors[].locationType
屬性值類型: 字符串(string)
父節點: error.errors
标明如何解釋location屬性。
示例：
{
"error":{
"errors": [{"locationType": ""}]
}
}
error.errors[].extendedHelp
屬性值類型: 字符串(string)
父節點: error.errors
help text的URI，使錯誤更易于理解。
示例：（注：原示例這(zhè)裡(lǐ)有筆誤，中文版這(zhè)裡(lǐ)做了校正）
{
"error":{
"errors": [{"extendedHelp": "http://url.to.more.details.example.com/"}]
}
}
error.errors[].sendReport
屬性值類型: 字符串(string)
父節點: error.errors
report form的URI，服務用它來收集錯誤狀态的數據。該URL會(huì)預先載入描述請求的參數
示例：
{
"error":{
"errors": [{"sendReport": "http://report.example.com/"}]
}
}
屬性順序
在JSON對(duì)象中屬性可有任意順序。然而，在某些情況下，有序的屬性可以幫助分析器快速解釋數據，并帶來更好(hǎo)的性能(néng)。在移動環境下的解析器就(jiù)是個例子，在這(zhè)種(zhǒng)情況下，性能(néng)和内存是至關重要的，不必要的解析也應盡量避免。
Kind屬性
Kind屬性應爲第一屬性
假設一個解析器負責將(jiāng)一個原始JSON流解析成(chéng)一個特定的對(duì)象。kind屬性會(huì)引導解析器將(jiāng)适合的對(duì)象實例化。因而它應該是JSON對(duì)象的第一個屬性。這(zhè)僅适用于對(duì)象有一個kind屬性的情況(通常可以在data和items屬性中找到)。
Items屬性
items應該是data對(duì)象的最後(hòu)一個屬性
這(zhè)使得閱讀每一個具體條目前前已讀所有的集合屬性。在有很多條目的情況下，這(zhè)樣(yàng)就(jiù)避免了開(kāi)發(fā)人員隻需要從數據的字段時(shí)不必要的解析這(zhè)些條目。
這(zhè)讓閱讀所有集合屬性先于閱讀單個條目。如遇多個條目的情況，當開(kāi)發(fā)者僅需要數據中的字段時(shí)，這(zhè)就(jiù)可避免解析不必要的條目。
屬性順序示例：
// "kind" 屬性區分 "album" 和 "photo".
// "Kind" 始終是它父對(duì)象的第一個屬性.
// "items" 屬性是 "data" 對(duì)象的最後(hòu)一個屬性.
{
"data": {
"kind": "album",
"title": "My Photo Album",
"description": "An album in the user's account",
"items": [
{
"kind": "photo",
"title": "My First Photo"
}
]
}
}
示例
YouTube JSON API
這(zhè)是YouTube JSON API響應對(duì)象的示例。你可以從中學(xué)到更多關于YouTube JSON API的内容：http://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html
{
"apiVersion": "2.0",
"data": {
"updated": "2010-02-04T19:29:54.001Z",
"totalItems": 6741,
"startIndex": 1,
"itemsPerPage": 1,
"items": [
{
"id": "BGODurRfVv4",
"uploaded": "2009-11-17T20:10:06.000Z",
"updated": "2010-02-04T06:25:57.000Z",
"uploader": "docchat",
"category": "Animals",
"title": "From service dog to SURFice dog",
"description": "Surf dog Ricochets inspirational video ...",
"tags": [
"Surf dog",
"dog surfing",
"dog",
"golden retriever",
],
"thumbnail": {
"default": "http://i.ytimg.com/vi/BGODurRfVv4/default.jpg",
"hqDefault": "http://i.ytimg.com/vi/BGODurRfVv4/hqdefault.jpg"
},
"player": {
"default": "http://www.youtube.com/watch?v=BGODurRfVv4&feature=youtube_gdata",
"mobile": "http://m.youtube.com/details?v=BGODurRfVv4"
},
"content": {
"1": "rtsp://v5.cache6.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYDSANFEgGUgZ2aWRlb3MM/0/0/0/video.3gp",
"5": "http://www.youtube.com/v/BGODurRfVv4?f=videos&app=youtube_gdata",
"6": "rtsp://v7.cache7.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYESARFEgGUgZ2aWRlb3MM/0/0/0/video.3gp"
},
"duration": 315,
"rating": 4.96,
"ratingCount": 2043,
"viewCount": 1781691,
"favoriteCount": 3363,
"commentCount": 1007,
"commentsAllowed": true
}
]
}
}
分頁示例
如何將(jiāng)Google搜索條目作爲JSON對(duì)象展現出來，對(duì)分頁變量也有特别關注。
這(zhè)個示例僅用作說(shuō)明。下面(miàn)的API實際上并不存在。
這(zhè)是Google搜索結果頁面(miàn)的示例： 
這(zhè)是該頁面(miàn)JSON形式的呈現：
{
"apiVersion": "2.1",
"id": "1",
"data": {
"query": "chicago style pizza",
"time": "0.1",
"currentItemCount": 10,
"itemsPerPage": 10,
"startIndex": 11,
"totalItems": 2700000,
"nextLink": "http://www.google.com/search?hl=en&q=chicago+style+pizza&start=20&sa=N"
"previousLink": "http://www.google.com/search?hl=en&q=chicago+style+pizza&start=0&sa=N",
"pagingLinkTemplate": "http://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N",
"items": [
{
"title": "Pizz'a Chicago Home Page"
// More fields for the search results
}
// More search results
]
}
}
這(zhè)是如何展現屏幕截圖中的色塊的例子（背景顔色對(duì)應下圖中的顔色）
- Results 11 - 20 of about 2,700,000 = startIndex
- Results 11 - 20 of about 2,700,000 = startIndex + currentItemCount - 1
- Results 11 - 20 of about 2,700,000 = totalItems
- Search results = items (formatted appropriately)
- Previous/Next = previousLink / nextLink
- Numbered links in "Gooooooooooogle" = Derived from "pageLinkTemplate". The developer is responsible for calculating the values for {index} and substituting those values into the "pageLinkTemplate". The pageLinkTemplate's {index} variable is calculated as follows:
- Index #1 = 0 * itemsPerPage = 0
- Index #2 = 2 * itemsPerPage = 10
- Index #3 = 3 * itemsPerPage = 20
- Index #N = N * itemsPerPage
附錄
附錄A:JavaScript中的保留字
下列JavaScript保留字應該避免在屬性名中使用
下面(miàn)的但在在JavaScript語言中被(bèi)保留，不能(néng)作爲在點訪問符中使用。這(zhè)份名單代表此時(shí)的最佳關鍵字的知識;列表可能(néng)會(huì)改變或根據您的特定的執行環境更改。
下面(miàn)是JavaScript語言中的保留字，且不能(néng)在點訪問符中使用。這(zhè)份清單集合了當前最新的關鍵字，該清單可能(néng)會(huì)根據具體的執行環境而有所變更或改變。
abstract
boolean break byte
case catch char class const continue
window default delete do double
else enum export extends
false final finally float for function
goto
if implements import in instanceof int interface
let long
native new null
package private protected public
return
short static super switch synchronized
this throw throws transient true try typeof
var volatile void
while with
yield
除了特别說(shuō)明，該頁面(miàn)的内容均由共同創作協議(CC BY 3.0)授權許可，示例代碼均由Apache 2.0許可證授權許可）
－EOF-
登錄 參與評論
評論
暫無任何評論