JSON API 規(guī)范

本文定義了一個標準的 JSON API規(guī)范，即一個應(yīng)用于 Web 前后端 Ajax 數(shù)據(jù)交互規(guī)范，用以定義客戶端如何獲取與修改資源，以及服務(wù)器如何響應(yīng)對應(yīng)請求。

JSON API 設(shè)計用來最小化請求的數(shù)量，以及客戶端與服務(wù)器間傳輸?shù)臄?shù)據(jù)量。在高效實現(xiàn)的同時，無需犧牲可讀性、靈活性和可發(fā)現(xiàn)性。

JSON API 需要使用 JSON API 媒體類型(application/vnd.api+json) 進行數(shù)據(jù)交互。

JSON API 服務(wù)器支持通過GET方法獲取資源。而且必須獨立實現(xiàn) HTTP POST, PUT 和 DELETE 方法的請求響應(yīng)，以支持資源的創(chuàng)建、更新和刪除。

JSON API服務(wù)器也可以選擇性支持HTTP PATCH方法 [RFC5789]和 JSON Patch格式 [RFC6902]，進行資源修改。JSON Patch 支持是可行的，因為理論上來說，JSON API 通過單一 JSON 文檔，反映域下的所有資源，并將 JSON 文檔作為資源操作介質(zhì)。在文檔頂層，依據(jù)資源類型分組。每個資源都通過文檔下的唯一路徑辨識。

相關(guān)的文檔模塊

##本文導(dǎo)航

[TOC]

規(guī)則約定

文檔中的關(guān)鍵字， "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",

"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 依據(jù)RFC 2119

[RFC2119]規(guī)范解釋。

文檔結(jié)構(gòu)

這一章節(jié)描述JSON API文檔結(jié)構(gòu)，通過媒體類型application/vnd.api+json標示。JSON API文檔使用javascript 對象(JSON)[RFC4627]定義。

盡管同種媒體類型用以請求和響應(yīng)文檔，但某些特性只適用于其中一種。差異在下面呈現(xiàn)。

Top Level

JSON 對象必須位于每個JSON API文檔的根級。這個對象定義文檔的“top level”。

文檔的top level必須包含請求資源或者請求資源集合的實例 (即主要資源)。

主要資源應(yīng)該以 資源類型 或者通用鍵 "data" 索引.

常見的APi Top Level主鍵說明

"code" - 自定義的資源響應(yīng)狀態(tài)編碼或錯誤碼，必須的鍵值，其值必須是整型數(shù)字，而且必須大于等于零。

"message"-可選，字符串，對 code 做進一步描述。當code的值 為 0 時，message 的值可選，當 code 的值大于 0 時，message 的值必填。

"data" - 主要資源的通用主鍵。可選值，用來存儲返回的實體數(shù)據(jù)。如果 data存在，data-value可為常規(guī)數(shù)據(jù)類型或復(fù)合數(shù)據(jù)類型。如果其為復(fù)合數(shù)據(jù)類型，則為“值對”數(shù)據(jù)結(jié)構(gòu)，或多維“值對”數(shù)據(jù)結(jié)構(gòu)。

"id" - 特定問題的唯一標示符。資源對象的保留字。

"href" - 提供特定問題更多細節(jié)的URI。資源對象的保留字。

"status" - 請求響應(yīng)的HTTP狀態(tài)碼，詳情請看http 狀態(tài)碼描述。

"title" - 簡短的，可讀性高的問題總結(jié)。除了國際化本地化處理之外，不同場景下，相同的問題，值是不應(yīng)該變動的。

"detail" - 針對該問題的高可讀性解釋。

"path" - 關(guān)聯(lián)資源中相關(guān)屬性的相對路徑。在單資源或單類型資源中出現(xiàn)的問題，這個值才是合適的。

"meta" - 資源的元信息，比如分頁信息等

"links" - 擴展資源關(guān)聯(lián)URLs的URL模板。資源對象的保留字

"linked" - 資源對象集合，按照類型分組，鏈接到主要資源或彼此(即鏈接資源)

資源表示

這一章節(jié)描述JSON API文檔如何表示資源。適用于主要資源和鏈接資源。

個體資源表示

個體資源使用單一“資源對象”(如下描述)或者包含資源ID(如下描述)的字符串表示。

The following post is represented as a resource object:

下面的 posts 表示一個資源對象：

{

"status":200,

"code":0,

"data": {

"id": "1",

// ... attributes of this post

}

}

這個 posts 用ID簡單地表示：

{

"code":0,

"posts": "1"

}

資源集合表示

任意數(shù)量資源的集合應(yīng)該使用資源對象數(shù)組，或者IDs數(shù)組，或者一個簡單的”集合對象“表示。

下面這個 posts 使用資源對象數(shù)組表示：

{

"code":0,

"posts": [{

"id": "1"

// ... attributes of this post

}, {

"id": "2"

// ... attributes of this post

}]

}

這個posts使用IDs數(shù)組表示：

{

"code":0,

"posts": ["1", "2"]

}

這些comments使用單一集合對象表示：

{

"code":0,

"comments": {

"href": "http://example.com/comments/5,12,17,20",

"ids": [ "5", "12", "17", "20" ],

"type": "comments"

}

}

多資源對象

多個資源對象有相同的內(nèi)部結(jié)構(gòu)，不管他們表示主要資源還是鏈接資源。

下面是一個可能出現(xiàn)在文檔中的post(即"posts"類型的一個資源)：

{

"code":0,

"posts": {

"id": "1",

"title": "Rails is Omakase"

}

}

在上面這個例子中，post的資源對象比較簡單：

//...

{

"id": "1",

"title": "Rails is Omakase"

}

//...

這一章節(jié)專注于資源對象，在完整JSON API文檔上下文環(huán)境之外。

資源屬性

資源對象有四個保留字:

"id"

"type"

"href"

"links"

資源對象中的其它鍵表示一個“屬性”。一個屬性值可以是任何JSON值。

資源 IDs

每一個資源對象應(yīng)該有一個唯一標示符，或者ID。如下所示，IDs可由服務(wù)器或者客戶端指定，and SHOULD be unique for a resource when scoped by its type. ID應(yīng)該使用 "id"鍵表示，值必須是字符串，且只包含字母，數(shù)字，連字符和下劃線。

URL 模板可以使用IDs來獲取關(guān)聯(lián)資源，如下所示。

在特殊場景下，客戶端與服務(wù)器之間的唯一標識符信息非必要，JSON API允許缺省IDs。

資源類型

每個資源對象的類型通常由它所在的上下文環(huán)境決定。如上面討論，資源對象在文檔中通過類型索引。

每一個資源對象可能包含 "type" 鍵來顯示指定類型。

當資源的類型在文檔中未聲明時，"type"鍵不可缺省。

資源 URLs

每一個資源的URL可能使用"href"鍵聲明。資源URLs應(yīng)該由服務(wù)器指定，因此通常包含在響應(yīng)文檔中。

//...

[{

"id": "1",

"href": "http://example.com/comments/1",

"body": "Mmmmmakase"

}, {

"id": "2",

"href": "http://example.com/comments/2",

"body": "I prefer unagi"

}]

//...

服務(wù)器對特定URLGET請求，響應(yīng)內(nèi)容必須包含資源。

通常在響應(yīng)文檔的根層級聲明URL 模板會更高效，而不是在每一個資源對象內(nèi)聲明獨立的URLs。

資源關(guān)聯(lián)

"links"鍵的值是一個表示鏈接資源的JSON對象，通過關(guān)聯(lián)名索引。

舉例來說，下面的post與一個author和一個comments集合相關(guān)聯(lián)：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": "9",

"comments": [ "5", "12", "17", "20" ]

}

}

//...

單對象關(guān)聯(lián)

單對象關(guān)聯(lián)必須使用上面所述單資源形式的一種來表示。

舉例來說，下面的post與一個author相關(guān)聯(lián)，通過ID標示：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": "17"

}

}

//...

下面是一個示例，鏈接的author用一個資源對象表示：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": {

"href": "http://example.com/people/17",

"id": "17",

"type": "people"

}

}

}

//...

空白的單對象關(guān)聯(lián)應(yīng)該用null值表示。舉例來說，下面的post沒有關(guān)聯(lián)author:

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": null

}

}

//...

多對象關(guān)聯(lián)

多對象關(guān)聯(lián)必須使用上述資源集合形式的一種來表示。

舉例來說，下面的post與多個comments關(guān)聯(lián)，通過IDs標示：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"comments": [ "5", "12", "17", "20" ]

}

}

//...

這是一個使用集合對象鏈接的comments數(shù)組：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"comments": {

"href": "http://example.com/comments/5,12,17,20",

"ids": [ "5", "12", "17", "20" ],

"type": "comments"

}

}

}

//...

空白的多對象關(guān)聯(lián)應(yīng)該使用空數(shù)組表示。舉例來說，下面的post沒有comments：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"comments": []

}

}

//...

集合對象

“集合對象”包含一個或多個元素：

"ids" - 關(guān)聯(lián)資源的IDs數(shù)組。

"type" - 資源類型

"href" - 關(guān)聯(lián)資源的URL(適用于響應(yīng)文檔)。

提供包含href屬性集合對象的服務(wù)器，必須響應(yīng)特定URL GET 請求，響應(yīng)內(nèi)容包含資源對象集合的關(guān)聯(lián)資源。

URL模板

頂層的 "links" 對象可用來聲明URL模板，從而依據(jù)資源對象類型獲取最終URLs。

舉例說明:

{

"code":0,

"links": {

"posts.comments": "http://example.com/comments?data={posts.id}"

},

"data": [{

"id": "1",

"title": "Rails is Omakase"

}, {

"id": "2",

"title": "The Parley Letter"

}]

}

在這個示例中，請求http://example.com/comments?posts=1 將會得到"Rails is Omakase"的comments，請求http://example.com/comments?posts=2 將會得到 "The Parley Letter"的comments.

下面是另外一個示例:

{

"code":0,

"links": {

"posts.comments": "http://example.com/comments/{posts.comments}"

},

"posts": [{

"id": "1",

"title": "Rails is Omakase",

"links": {

"comments": [ "1", "2", "3", "4" ]

}

}]

}

在這個示例中，處理每個post"links"區(qū)塊內(nèi)的特定數(shù)組，以擴展posts.comments變量。URI模板規(guī)范 [RFC6570]聲明默認處理方式，使用%編碼(即encodeURIComponent() javascript原生方法)編碼每一個元素，然后用逗號連接。在這個示例中，請求http://example.com/comments/1,2,3,4 ，將會獲取一個comments列表。

頂層 "links"對象具有以下行為:

每個鍵使用點分隔路徑，指向重復(fù)的關(guān)聯(lián)。路徑以特定資源類型名開頭，遍歷相關(guān)的資源。舉例來 說，"posts.comments"指向每個"posts"對象的"comments"關(guān)聯(lián).

每個鍵的值作為URL模板處理。

每個path指向的資源，就像是使用實際指定的非URL值擴展URL模板形成的關(guān)聯(lián)。

這是另外一個使用單對象關(guān)聯(lián)的示例：

{

"code":0,

"links": {

"posts.author": "http://example.com/people/{posts.author}"

},

"posts": [{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": "12"

}

}, {

"id": "2",

"title": "The Parley Letter",

"links": {

"author": "12"

}

}, {

"id": "3",

"title": "Dependency Injection is Not a Virtue",

"links": {

"author": "12"

}

}]

}

這個實例中，三個posts指向author的URL都為http://example.com/people/12.

頂層URL模板允許指定關(guān)聯(lián)作為IDs，但是不要求客戶端硬編碼來獲取URLs的信息.

注意：為防止沖突，單獨資源對象的links對象優(yōu)先級高于頂層的links對象。

復(fù)合文檔

為減少HTTP請求，響應(yīng)需要返回所請求的主要資源，同時可以選擇性的包含鏈接資源。這樣的響應(yīng)稱作“復(fù)合文檔”。

在復(fù)合文檔中，鏈接資源必須作為資源對象，包含在文檔頂層"linked"對象中，依據(jù)類型，組合到不同數(shù)組中。

每個關(guān)聯(lián)的類型，可以在資源層級，或頂層"links"對象層級，使用"type"鍵指定。能夠輔助客戶端查詢鏈接資源對象。

{

"code":0,

"links": {

"posts.author": {

"href": "http://example.com/people/{posts.author}",

"type": "people"

},

"posts.comments": {

"href": "http://example.com/comments/{posts.comments}",

"type": "comments"

}

},

"posts": [{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": "9",

"comments": [ "1", "2", "3" ]

}}, {

"id": "2",

"title": "The Parley Letter",

"links": {

"author": "9",

"comments": [ "4", "5" ]

}}, {

"id": "1",

"title": "Dependency Injection is Not a Virtue",

"links": {

"author": "9",

"comments": [ "6" ]

}

}],

"linked": {

"people": [{

"id": "9",

"name": "@d2h"

}],

"comments": [{

"id": "1",

"body": "Mmmmmakase"

}, {

"id": "2",

"body": "I prefer unagi"

}, {

"id": "3",

"body": "What's Omakase?"

}, {

"id": "4",

"body": "Parley is a discussion, especially one between enemies"

}, {

"id": "5",

"body": "The parsley letter"

}, {

"id": "6",

"body": "Dependency Injection is Not a Vice"

}]

}

}

這種處理方式，保證隨每個響應(yīng)返回每個文檔的單例，即使當相同的文檔被多次引用時(這個實例中三個posts的author)。沿著這種方式，如果主要文檔鏈接到另外的主要或鏈接文檔，在"linked"對象中也不應(yīng)該重復(fù)。

URLs

關(guān)聯(lián)文檔

確定API的URL結(jié)構(gòu)時，考慮把所有的資源放置于單一“關(guān)聯(lián)文檔"是有用的，在關(guān)聯(lián)文檔中，每個資源都被分配唯一路徑。在文檔頂層，資源依據(jù)類型分組。在分類資源集合中，單獨資源通過ID索引。其屬性和links，依據(jù)資源對象結(jié)構(gòu)，唯一分配。

關(guān)聯(lián)文檔的概念，用于為資源及資源關(guān)系確定合適的URLs。重要的一點，出于不同目標和限制，用于傳輸資源的不同文檔中，關(guān)聯(lián)文檔的結(jié)構(gòu)有輕微差異。例如，在關(guān)聯(lián)文檔中的資源集當做集合處理，因為元素必須通過ID訪問，在傳輸文檔中的資源集當做數(shù)組處理，因為順序比較重要。

資源集合URLs

資源集合的URL應(yīng)該依據(jù)資源類型確定。

例如，”photos”類型的資源集合應(yīng)該使用這種URL:

/photos

單獨資源URLs

資源集應(yīng)該作為集合，依據(jù)資源ID索引。單獨資源的URL通過為集合URL添加資源ID生成。

例如，ID為"1"的photo使用這種URL:

/photos/1

多個單獨資源的URL通過為集合URL添加逗號分隔的資源IDs列表生成。

例如，IDs為"1", "2", "3"的photos使用這種URL:

/photos/1,2,3

替代性URLs

資源的替代性URLs可以選擇在響應(yīng)中指定，或者通過"href"或URL模板指定。

關(guān)聯(lián) URLs

添加/links/到資源URL后面，即得到訪問特定資源的關(guān)聯(lián)資源URL。相對路徑與資源對象內(nèi)部結(jié)構(gòu)保持一致。

例如，photo的comments鏈接集使用這種URL:

/photos/1/links/comments

A photo's reference to an individual linked photographer will have the URL:

photo的photographer鏈接使用這種URL:

/photos/1/links/photographer

服務(wù)器使用單獨資源響應(yīng)單對象關(guān)聯(lián)，使用資源集合響應(yīng)多對象關(guān)聯(lián)。

資源獲取

資源，或者資源集合，通過向URL發(fā)出GET請求獲取。

響應(yīng)內(nèi)容可以使用如下所示的特點，進一步細化。

過濾

服務(wù)器可以選擇性支持，依據(jù)指定標準進行資源過濾。

通過向資源集合的基準URL添加過濾參數(shù)，來支持資源過濾。

例如，下面是請求與特定post關(guān)聯(lián)的所有comments:

GET /comments?posts=1

使用這種方案，單一請求可以使用多過濾器：

GET /comments?posts=1&author=12

這種規(guī)范僅支持基于嚴格匹配的資源過濾。API允許使用的額外過濾器應(yīng)該在它的側(cè)寫中指定。 (見

Extending)

內(nèi)鏈資源

服務(wù)器可以選擇性支持，返回包含主要資源和鏈接資源對象的復(fù)合文檔。

默認情況下，后端返回鏈接主要資源的資源對象。

后端也可以基于請求中include的參數(shù)，支持自定義鏈接資源。參數(shù)應(yīng)該指定一個或者多個，相對于主要資源的相對路徑。如果指定參數(shù)值，只有請求的鏈接資源，應(yīng)該隨主要資源返回。

例如，comments可以通過post請求:

GET /posts/1?include=comments

為請求鏈接到其他資源的資源，需要指定每個關(guān)聯(lián)的點分隔路徑。

GET /posts/1?include=comments.author

注意：對comments.author的請求，在響應(yīng)中不應(yīng)該自動包含comments資源(盡管comments也需要顯式查詢，以獲取authors響應(yīng)請求)。

多鏈接資源可以使用點分隔列表請求：

GET /posts/1?include=author,comments,comments.author

稀疏字段

服務(wù)器可以選擇性支持，僅返回資源對象的指定字段。

后端可以基于fields參數(shù)，以支持返回主要資源的指定字段。

GET /people?fields=id,name,age

后端可以基于fields[TYPE]參數(shù)，以支持返回任意類型資源的特定字段。

GET /posts?include=author&fields[posts]=id,title&fields[people]=id,name

若沒有指定類型對象的字段，或者后端不支持field或fields[TYPE]參數(shù)，后端會默認返回資源對象的所有字段。

后端可以選擇總是返回有限的，未指定的字段集，例如id or href.

注意： fields 和 fields[TYPE]不能混合使用。如果使用后者，那么必須與主要資源類型同時使用。

排序

服務(wù)器可以選擇性支持，基于特定標準對資源集合排序。

后端基于sort參數(shù)，以支持主要資源類型的排序。

GET /people?sort=age

后端支持多字段排序，將sort值設(shè)置為點分隔值即可。排序標準用以獲取特定順序。

GET /people?sort=age,name

默認排序方式為升序排序。任意排序字段，使用-前綴指定降序排序。

GET /posts?sort=-created,title

上面的示例應(yīng)該首先返回最新的posts。同一天創(chuàng)建的posts，依據(jù)title值進行字母升序排列。

后端基于sort[TYPE]參數(shù)，以支持對任意資源類型排序。

GET /posts?include=author&sort[posts]=-created,title&sort[people]=name

如果沒有指定排序方式，或者后端不支持sort和sort[TYPE]，后端將會返回使用重復(fù)算法排序的資源對象。換言之，資源應(yīng)該總是以相同順序返回，即使排序規(guī)則沒有指定。

注意：sort和sort[TYPE]不能混用。如果使用后者，必須與主要資源一同使用。

創(chuàng)建，更新，刪除資源

服務(wù)器可能支持資源獲取，創(chuàng)建，更新和刪除。

服務(wù)器允許單次請求，更新多個資源，如下所述。多個資源更新必須完全成功或者失敗，不允許部分更新成功。

任何包含內(nèi)容的請求，必須包含Content-Type:application/vnd.api+json請求頭。

創(chuàng)建資源

支持資源創(chuàng)建的服務(wù)器，必須支持創(chuàng)建單獨的資源，可以選擇性支持一次請求，創(chuàng)建多個資源。

向表示待創(chuàng)建資源所屬資源集的URL，發(fā)出POST請求，創(chuàng)建一個或多個資源。

創(chuàng)建單獨資源

創(chuàng)建單獨資源的請求必須包含單一主要資源對象。

例如，新photo可以通過如下請求創(chuàng)建：

POST /photos

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"photos": {

"title": "Ember Hamster",

"src": "http://example.com/images/productivity.png"

}

}

創(chuàng)建多個資源

創(chuàng)建多個資源的請求必須包含主要主要資源集合。

例如，多個photos通過如下請求創(chuàng)建：

POST /photos

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"photos": [{

"title": "Ember Hamster",

"src": "http://example.com/images/productivity.png"

}, {

"title": "Mustaches on a Stick",

"src": "http://example.com/images/mustaches.png"

}]

}

響應(yīng)

201 狀態(tài)碼

服務(wù)器依據(jù)[HTTP semantics](http://tools.ietf.org/html/draft-ietf-

httpbis-p2-semantics-22#section-6.3)規(guī)范，響應(yīng)成功的資源創(chuàng)建請求。

當一個或多個資源創(chuàng)建成功，服務(wù)器返回201 Created狀態(tài)碼。

響應(yīng)必須包含Location頭，用以標示請求創(chuàng)建所有資源的位置。

如果創(chuàng)建了單個資源，且資源對象包含href鍵，Location URL必須匹配href值。

響應(yīng)必須含有一個文檔，用以存儲所創(chuàng)建的主要資源。如果缺失，客戶端則判定資源創(chuàng)建時，傳輸?shù)奈臋n未經(jīng)修改。

HTTP/1.1 201 Created

Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000

Content-Type: application/vnd.api+json

{

"photos": {

"id": "550e8400-e29b-41d4-a716-446655440000",

"href": "http://example.com/photos/550e8400-e29b-41d4-a716-446655440000",

"title": "Ember Hamster",

"src": "http://example.com/images/productivity.png"

}

}

其它響應(yīng)

服務(wù)器可能使用其它HTTP錯誤狀態(tài)碼反映錯誤。客戶端必須依據(jù)HTTP規(guī)范處理這些錯誤信息。如下所述，錯誤細節(jié)可能會一并返回。

客戶端生成 IDs

請求創(chuàng)建一個或多個資源時，服務(wù)器可能接受客戶端生成IDs。IDs必須使用"id"鍵來指定，其值必須正確生成，且為格式化的UUID。

例如：

POST /photos

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"photos": {

"id": "550e8400-e29b-41d4-a716-446655440000",

"title": "Ember Hamster",

"src": "http://example.com/images/productivity.png"

}

}

更新資源

支持資源更新的服務(wù)器必須支持單個資源的更新，可以選擇性的支持單次請求更新多個資源。

向表示單獨資源或多個單獨資源的URL發(fā)出PUT請求，即可進行資源更新。

更新單獨資源

為更新單獨資源，向表示資源的URL發(fā)出PUT請求。請求必須包含一個頂層資源對象。

例如：

PUT /articles/1

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"articles": {

"id": "1",

"title": "To TDD or Not"

}

}

更新多個資源

向表示多個單獨資源(不是全部的資源集合)的URL發(fā)出PUT請求，即可更新多個資源。請求必須包含頂層資源對象集合，且每個資源具有“id"元素。

例如：

PUT /articles/1,2

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"articles": [{

"id": "1",

"title": "To TDD or Not"

}, {

"id": "2",

"title": "LOL Engineering"

}]

}

更新屬性

要更新資源的一個或多個屬性，主要資源對象應(yīng)該只包括待更新的屬性。資源對象缺省的屬性將不會更新。

例如，下面的PUT請求，僅會更新article的title和text屬性。

PUT /articles/1

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"articles": {

"id": "1",

"title": "To TDD or Not",

"text": "TLDR; It's complicated... but check your test coverage regardless."

}

}

更新關(guān)聯(lián)

更新單對象關(guān)聯(lián)

單對象關(guān)聯(lián)更新，可以在PUT請求資源對象中包含links鍵，從而與其它屬性一起更新。

例如，下面的PUT請求將會更新article的title和author屬性：

PUT /articles/1

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"articles": {

"title": "Rails is a Melting Pot",

"links": {

"author": "1"

}

}

}

若要移除單對象關(guān)聯(lián)，指定null作為值即可。

另外，單對象關(guān)聯(lián)也可以通過它的關(guān)聯(lián)URL訪問。

向關(guān)聯(lián)URL發(fā)出帶有主要資源的POST請求，即可添加單對象關(guān)聯(lián)。

例如：

POST /articles/1/links/author

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"people": "12"

}

向關(guān)聯(lián)URL發(fā)出DELETE請求，即可刪除單對象關(guān)聯(lián)。例如：

DELETE /articles/1/links/author

更新多關(guān)聯(lián)對象

更新多對象關(guān)聯(lián)，可以在PUT請求中資源對象包含links鍵，從而與其它屬性一起更新。

例如，下面PUT請求完全替換article的tags。

PUT /articles/1

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"articles": {

"id": "1",

"title": "Rails is a Melting Pot",

"links": {

"tags": ["2", "3"]

}

}

}

若要移除多對象關(guān)聯(lián)，指定空數(shù)組[]為值即可。

在分布式系統(tǒng)中，完全替換一個數(shù)據(jù)集合并不總是合適。替換方案是允許單獨的添加或移除關(guān)聯(lián)。

為促進細化訪問，多對象關(guān)聯(lián)也可以通過關(guān)聯(lián)URL訪問。

向關(guān)聯(lián)URL發(fā)出帶有主要資源的POST請求，即可添加多對象關(guān)聯(lián)。

POST /articles/1/links/comments

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"comments": ["1", "2"]

}

向關(guān)聯(lián)URL發(fā)出DELETE請求，即可刪除多對象對象關(guān)聯(lián)。例如：

DELETE /articles/1/links/tags/1

向關(guān)聯(lián)URL發(fā)出DELETE請求，即可刪除多個多對象對象關(guān)聯(lián)。例如：

DELETE /articles/1/links/tags/1,2

響應(yīng)

204 No Content

如果更新成功，且客戶端屬性保持最新，服務(wù)器必須返回204 No Content狀態(tài)碼。適用于PUT請求，以及僅調(diào)整links，不涉及其它屬性的POST, DELETE請求。

200 OK

如果服務(wù)器接受更新，但是在請求指定內(nèi)容之外做了資源修改，必須響應(yīng)200 OK以及更新的資源實例，像是向此URL發(fā)出GET請求。

其它響應(yīng)

服務(wù)器使用其它HTTP錯誤狀態(tài)碼反映錯誤。客戶端必須依據(jù)HTTP規(guī)范處理這些錯誤信息。如下所述，錯誤細節(jié)可能會一并返回。

資源刪除

向資源URL發(fā)出DELETE請求即可刪除單個資源。

DELETE /photos/1

服務(wù)器可以選擇性的支持，在一個請求里刪除多個資源。

DELETE /photos/1,2,3

響應(yīng)

204 No Content

如果刪除請求成功，服務(wù)器必須返回204 No Content 狀態(tài)碼。

其它響應(yīng)

服務(wù)器使用其它HTTP錯誤狀態(tài)碼反映錯誤。客戶端必須依據(jù)HTTP規(guī)范處理這些錯誤信息。如下所述，錯誤細節(jié)可能會一并返回。

Errors

錯誤對象是特殊化的資源對象，可能在響應(yīng)中一并返回，用以提供執(zhí)行操作遭遇問題的額外信息。在在JSON API文檔頂層，"errors"對應(yīng)值即為錯誤對象集合，此時文檔不應(yīng)該包含其它頂層資源。

錯誤對象可能有以下元素：

"id" - 特定問題的唯一標示符。

"href" - 提供特定問題更多細節(jié)的URI。

"status" - 適用于這個問題的HTTP狀態(tài)碼，使用字符串表示。

"code" - 應(yīng)用特定的錯誤碼，以字符串表示。

"title" - 簡短的，可讀性高的問題總結(jié)。除了國際化本地化處理之外，不同場景下，相同的問題，值是不應(yīng)該變動的。

"detail" - 針對該問題的高可讀性解釋。

"links" - 可以在請求文檔中取消應(yīng)用的關(guān)聯(lián)資源。

"path" - 關(guān)聯(lián)資源中相關(guān)屬性的相對路徑。在單資源或單類型資源中出現(xiàn)的問題，這個值才是合適的。

額外的元素可以在錯誤對象中指定。

實現(xiàn)接口可以選擇使用其它的errors媒體類型。

PATCH Support

JSON API服務(wù)器可以選擇性支持，遵循JSON Patch規(guī)范[RFC6902]的HTTP PATCH請求。上面提到使用POST, PUT 和 DELETE進行的操作，JSON Patch都擁有等效操作。從這里開始，PATCH請求發(fā)出的JSON Patch操作，都被簡單的稱作“PATCH"操作。

PATCH請求必須聲明Content-Type:application/json-patch+json頭。

PATCH操作必須作為數(shù)組發(fā)送，以遵循JSON Patch規(guī)范。服務(wù)器可能會限制頂層數(shù)組類型，順序和操作數(shù)量。

請求 URLs

每個PATCH請求的URL應(yīng)該映射待更新的資源或關(guān)聯(lián)。

PATCH操作內(nèi)的每個"path"應(yīng)該相對于請求URL。請求URL和PATCH操作的"path"是附加的，合并后獲取特定資源，集合，屬性，或者關(guān)聯(lián)目標。

PATCH操作可以在API的根URL使用。此時，PATCH操作的"path"必須包含完整的資源URL。API表示的任意資源都可以進行常規(guī)的"fire hose"更新。如上所述，服務(wù)器可能會限制類型，排序和批量操作數(shù)量。

創(chuàng)建資源with PATCH

要創(chuàng)建資源，執(zhí)行"add"操作， "path"指向?qū)?yīng)資源集合的末尾 ("/-")。"value"必須包含一個資源對象。

比如，新photo通過如下請求創(chuàng)建：

PATCH /photos

Content-Type: application/json-patch+json

Accept: application/json

[

{

"op": "add",

"path": "/-",

"value": {

"title": "Ember Hamster",

"src": "http://example.com/images/productivity.png"

}

}

]

更新屬性with PATCH

要更新屬性，執(zhí)行"replace" 操作，"path"值指定屬性名。

例如，下面請求只更新/photos/1的src值。

PATCH /photos/1

Content-Type: application/json-patch+json

[

{

"op": "replace",

"path": "/src",

"value": "http://example.com/hamster.png"

}

]

更新關(guān)聯(lián)with PATCH

要更新關(guān)聯(lián)，向?qū)?yīng)的關(guān)聯(lián)URL發(fā)出合適的PATCH操作即可。

服務(wù)器可能支持更高層級的更新，像資源的URL(甚至是API的根URL)。如上所述，請求URL和每個操作的"path"是附加的，合并后獲得特定關(guān)聯(lián)URL目標。

關(guān)聯(lián)更新with PATCH

要更新單對象關(guān)聯(lián)，對指向關(guān)聯(lián)的URL和"path" 執(zhí)行"replace"操作。

例如：下面請求更新article的author：

PATCH /article/1/links/author

Content-Type: application/json-patch+json

[

{

"op": "replace",

"path": "/",

"value": "1"

}

]

要移除單對象關(guān)聯(lián)，對關(guān)聯(lián)執(zhí)行remove操作。例如：

PATCH /article/1/links/author

Content-Type: application/json-patch+json

[

{

"op": "remove",

"path": "/"

}

]

更新多對象關(guān)聯(lián) with PATCH

盡管在GET響應(yīng)中，多對象關(guān)聯(lián)以JSON數(shù)組形式表示，但是更新時更像是集合。

要添加元素到多對象關(guān)聯(lián)，執(zhí)行指向關(guān)聯(lián)URL的"add" 請求。由于操作指向集合末尾， "path" 必須以"/-"結(jié)尾。

例如，考慮下面的GET請求：

GET /photos/1

Content-Type: application/vnd.api+json

{

"code":0,

"links": {

"comments": "http://example.com/comments/{comments}"

},

"photos": {

"id": "1",

"href": "http://example.com/photos/1",

"title": "Hamster",

"src": "images/hamster.png",

"links": {

"comments": [ "1", "5", "12", "17" ]

}

}

}

向PATCH請求執(zhí)行add操作，即可將comment 30 轉(zhuǎn)移到這個photo。

PATCH /photos/1/links/comments

Content-Type: application/json-patch+json

[

{

"op": "add",

"path": "/-",

"value": "30"

}

]

要移除多對象關(guān)聯(lián)，對指向關(guān)聯(lián)對象的URL執(zhí)行"remove"操作。因為操作目標是元素集合，"path"必須以"/"結(jié)尾。

比如，要移除photo的comment 5，執(zhí)行"remove"操作：

PATCH /photos/1/links/comments

Content-Type: application/json-patch+json

[

{

"op": "remove",

"path": "/5"

}

]

刪除資源with PATCH

要刪除資源，對指向資源的 URL 和"path"執(zhí)行 "remove" 操作。

例如，photo 1 能使用下面請求刪除：

PATCH /photos/1

Content-Type: application/json-patch+json

Accept: application/vnd.api+json

[

{

"op": "remove",

"path": "/"

}

]

響應(yīng)

204 No Content

若PATCH請求成功，客戶端當前的屬性保持最新，服務(wù)器必須響應(yīng)204 No Content 狀態(tài)碼。

200 OK

如果服務(wù)器接受更新，但是在請求指定內(nèi)容之外做了資源修改，必須響應(yīng)200 OK以及更新的資源實例。

服務(wù)器必須指定Content-Type:application/json頭。響應(yīng)內(nèi)容必須包含JSON對象數(shù)組，每個對象必須遵循JSON API媒體類型(application/vnd.api+json)。數(shù)組中的響應(yīng)對象必須有序，并且對應(yīng)請求文檔操作。

例如，一個請求以分離操作，創(chuàng)建兩個photos。

PATCH /photos

Content-Type: application/json-patch+json

Accept: application/json

[

{

"op": "add",

"path": "/-",

"value": {

"title": "Ember Hamster",

"src": "http://example.com/images/productivity.png"

}

},

{

"op": "add",

"path": "/-",

"value": {

"title": "Mustaches on a Stick",

"src": "http://example.com/images/mustaches.png"

}

}

]

響應(yīng)內(nèi)容在數(shù)組中包含對應(yīng)的JSON API文檔。

HTTP/1.1 200 OK

Content-Type: application/json

[

{

"photos": [{

"id": "123",

"title": "Ember Hamster",

"src": "http://example.com/images/productivity.png"

}]

}, {

"photos": [{

"id": "124",

"title": "Mustaches on a Stick",

"src": "http://example.com/images/mustaches.png"

}]

}

]

其它響應(yīng)

當服務(wù)器執(zhí)行PATCH請求時出現(xiàn)一個或多個問題，應(yīng)該在響應(yīng)中指定最合適的HTTP狀態(tài)碼。客戶端依據(jù)HTTP規(guī)范解析錯誤。

服務(wù)器可以選擇在第一個問題出現(xiàn)時，立刻終止PATCH 操作，或者繼續(xù)執(zhí)行，遇到多個問題。例如，服務(wù)器可能多屬性更新，然后返回在一個響應(yīng)里返回多個校驗問題。

當服務(wù)器單個請求遇到多個問題，響應(yīng)中應(yīng)該指定最通用可行的HTTP錯誤碼。例如，400 Bad Request適用于多個4xx errors，500 Internal Server Error適用于多個5xx errors。

服務(wù)器可能會返回與每個操作對應(yīng)的錯誤對象。服務(wù)器需要指定Content-Type:application/json頭，響應(yīng)體必須包含JSON對象數(shù)組，每個對象必須遵循JSON API媒體類型 (application/vnd.api+json)。數(shù)組中的響應(yīng)對象，必須是有序，且與請求文檔中的操作相對應(yīng)。每個響應(yīng)對象應(yīng)該僅包含error對象，當錯誤發(fā)生時，沒有操作會完全成功。每個特定操作的錯誤碼，應(yīng)該在每個error對象 "status" 元素反映。

HTTP 緩存

服務(wù)器可能會使用遵循HTTP 1.1規(guī)范的HTTP 緩存頭 (ETag, Last-Modified)。

總結(jié)

以上是生活随笔為你收集整理的json key 命名规范_jsonapi的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。