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