JSON API 規范

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

JSON API 設計用來最小化請求的數量，以及客戶端與服務器間傳輸的數據量。在高效實現的同時，無需犧牲可讀性、靈活性和可發現性。

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

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

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

相關的文檔模塊

##本文導航

[TOC]

規則約定

文檔中的關鍵字， "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",

"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 依據RFC 2119

[RFC2119]規范解釋。

文檔結構

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

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

Top Level

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

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

主要資源應該以 資源類型 或者通用鍵 "data" 索引.

常見的APi Top Level主鍵說明

"code" - 自定義的資源響應狀態編碼或錯誤碼，必須的鍵值，其值必須是整型數字，而且必須大于等于零。

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

"data" - 主要資源的通用主鍵。可選值，用來存儲返回的實體數據。如果 data存在，data-value可為常規數據類型或復合數據類型。如果其為復合數據類型，則為“值對”數據結構，或多維“值對”數據結構。

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

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

"status" - 請求響應的HTTP狀態碼，詳情請看http 狀態碼描述。

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

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

"path" - 關聯資源中相關屬性的相對路徑。在單資源或單類型資源中出現的問題，這個值才是合適的。

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

"links" - 擴展資源關聯URLs的URL模板。資源對象的保留字

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

資源表示

這一章節描述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"

}

資源集合表示

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

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

{

"code":0,

"posts": [{

"id": "1"

// ... attributes of this post

}, {

"id": "2"

// ... attributes of this post

}]

}

這個posts使用IDs數組表示：

{

"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"

}

}

多資源對象

多個資源對象有相同的內部結構，不管他們表示主要資源還是鏈接資源。

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

{

"code":0,

"posts": {

"id": "1",

"title": "Rails is Omakase"

}

}

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

//...

{

"id": "1",

"title": "Rails is Omakase"

}

//...

這一章節專注于資源對象，在完整JSON API文檔上下文環境之外。

資源屬性

資源對象有四個保留字:

"id"

"type"

"href"

"links"

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

資源 IDs

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

URL 模板可以使用IDs來獲取關聯資源，如下所示。

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

資源類型

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

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

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

資源 URLs

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

//...

[{

"id": "1",

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

"body": "Mmmmmakase"

}, {

"id": "2",

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

"body": "I prefer unagi"

}]

//...

服務器對特定URLGET請求，響應內容必須包含資源。

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

資源關聯

"links"鍵的值是一個表示鏈接資源的JSON對象，通過關聯名索引。

舉例來說，下面的post與一個author和一個comments集合相關聯：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": "9",

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

}

}

//...

單對象關聯

單對象關聯必須使用上面所述單資源形式的一種來表示。

舉例來說，下面的post與一個author相關聯，通過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"

}

}

}

//...

空白的單對象關聯應該用null值表示。舉例來說，下面的post沒有關聯author:

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"author": null

}

}

//...

多對象關聯

多對象關聯必須使用上述資源集合形式的一種來表示。

舉例來說，下面的post與多個comments關聯，通過IDs標示：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

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

}

}

//...

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

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"comments": {

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

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

"type": "comments"

}

}

}

//...

空白的多對象關聯應該使用空數組表示。舉例來說，下面的post沒有comments：

//...

{

"id": "1",

"title": "Rails is Omakase",

"links": {

"comments": []

}

}

//...

集合對象

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

"ids" - 關聯資源的IDs數組。

"type" - 資源類型

"href" - 關聯資源的URL(適用于響應文檔)。

提供包含href屬性集合對象的服務器，必須響應特定URL GET 請求，響應內容包含資源對象集合的關聯資源。

URL模板

頂層的 "links" 對象可用來聲明URL模板，從而依據資源對象類型獲取最終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"區塊內的特定數組，以擴展posts.comments變量。URI模板規范 [RFC6570]聲明默認處理方式，使用%編碼(即encodeURIComponent() javascript原生方法)編碼每一個元素，然后用逗號連接。在這個示例中，請求http://example.com/comments/1,2,3,4 ，將會獲取一個comments列表。

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

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

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

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

這是另外一個使用單對象關聯的示例：

{

"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模板允許指定關聯作為IDs，但是不要求客戶端硬編碼來獲取URLs的信息.

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

復合文檔

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

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

每個關聯的類型，可以在資源層級，或頂層"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"

}]

}

}

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

URLs

關聯文檔

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

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

資源集合URLs

資源集合的URL應該依據資源類型確定。

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

/photos

單獨資源URLs

資源集應該作為集合，依據資源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可以選擇在響應中指定，或者通過"href"或URL模板指定。

關聯 URLs

添加/links/到資源URL后面，即得到訪問特定資源的關聯資源URL。相對路徑與資源對象內部結構保持一致。

例如，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

服務器使用單獨資源響應單對象關聯，使用資源集合響應多對象關聯。

資源獲取

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

響應內容可以使用如下所示的特點，進一步細化。

過濾

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

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

例如，下面是請求與特定post關聯的所有comments:

GET /comments?posts=1

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

GET /comments?posts=1&author=12

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

Extending)

內鏈資源

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

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

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

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

GET /posts/1?include=comments

為請求鏈接到其他資源的資源，需要指定每個關聯的點分隔路徑。

GET /posts/1?include=comments.author

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

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

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

稀疏字段

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

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

GET /people?fields=id,name,age

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

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

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

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

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

排序

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

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

GET /people?sort=age

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

GET /people?sort=age,name

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

GET /posts?sort=-created,title

上面的示例應該首先返回最新的posts。同一天創建的posts，依據title值進行字母升序排列。

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

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

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

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

創建，更新，刪除資源

服務器可能支持資源獲取，創建，更新和刪除。

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

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

創建資源

支持資源創建的服務器，必須支持創建單獨的資源，可以選擇性支持一次請求，創建多個資源。

向表示待創建資源所屬資源集的URL，發出POST請求，創建一個或多個資源。

創建單獨資源

創建單獨資源的請求必須包含單一主要資源對象。

例如，新photo可以通過如下請求創建：

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"

}

}

創建多個資源

創建多個資源的請求必須包含主要主要資源集合。

例如，多個photos通過如下請求創建：

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"

}]

}

響應

201 狀態碼

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

httpbis-p2-semantics-22#section-6.3)規范，響應成功的資源創建請求。

當一個或多個資源創建成功，服務器返回201 Created狀態碼。

響應必須包含Location頭，用以標示請求創建所有資源的位置。

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

響應必須含有一個文檔，用以存儲所創建的主要資源。如果缺失，客戶端則判定資源創建時，傳輸的文檔未經修改。

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"

}

}

其它響應

服務器可能使用其它HTTP錯誤狀態碼反映錯誤。客戶端必須依據HTTP規范處理這些錯誤信息。如下所述，錯誤細節可能會一并返回。

客戶端生成 IDs

請求創建一個或多個資源時，服務器可能接受客戶端生成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"

}

}

更新資源

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

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

更新單獨資源

為更新單獨資源，向表示資源的URL發出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發出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"

}]

}

更新屬性

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

例如，下面的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."

}

}

更新關聯

更新單對象關聯

單對象關聯更新，可以在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"

}

}

}

若要移除單對象關聯，指定null作為值即可。

另外，單對象關聯也可以通過它的關聯URL訪問。

向關聯URL發出帶有主要資源的POST請求，即可添加單對象關聯。

例如：

POST /articles/1/links/author

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

"people": "12"

}

向關聯URL發出DELETE請求，即可刪除單對象關聯。例如：

DELETE /articles/1/links/author

更新多關聯對象

更新多對象關聯，可以在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"]

}

}

}

若要移除多對象關聯，指定空數組[]為值即可。

在分布式系統中，完全替換一個數據集合并不總是合適。替換方案是允許單獨的添加或移除關聯。

為促進細化訪問，多對象關聯也可以通過關聯URL訪問。

向關聯URL發出帶有主要資源的POST請求，即可添加多對象關聯。

POST /articles/1/links/comments

Content-Type: application/vnd.api+json

Accept: application/vnd.api+json

{

"code":0,

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

}

向關聯URL發出DELETE請求，即可刪除多對象對象關聯。例如：

DELETE /articles/1/links/tags/1

向關聯URL發出DELETE請求，即可刪除多個多對象對象關聯。例如：

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

響應

204 No Content

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

200 OK

如果服務器接受更新，但是在請求指定內容之外做了資源修改，必須響應200 OK以及更新的資源實例，像是向此URL發出GET請求。

其它響應

服務器使用其它HTTP錯誤狀態碼反映錯誤。客戶端必須依據HTTP規范處理這些錯誤信息。如下所述，錯誤細節可能會一并返回。

資源刪除

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

DELETE /photos/1

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

DELETE /photos/1,2,3

響應

204 No Content

如果刪除請求成功，服務器必須返回204 No Content 狀態碼。

其它響應

服務器使用其它HTTP錯誤狀態碼反映錯誤。客戶端必須依據HTTP規范處理這些錯誤信息。如下所述，錯誤細節可能會一并返回。

Errors

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

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

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

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

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

"code" - 應用特定的錯誤碼，以字符串表示。

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

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

"links" - 可以在請求文檔中取消應用的關聯資源。

"path" - 關聯資源中相關屬性的相對路徑。在單資源或單類型資源中出現的問題，這個值才是合適的。

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

實現接口可以選擇使用其它的errors媒體類型。

PATCH Support

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

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

PATCH操作必須作為數組發送，以遵循JSON Patch規范。服務器可能會限制頂層數組類型，順序和操作數量。

請求 URLs

每個PATCH請求的URL應該映射待更新的資源或關聯。

PATCH操作內的每個"path"應該相對于請求URL。請求URL和PATCH操作的"path"是附加的，合并后獲取特定資源，集合，屬性，或者關聯目標。

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

創建資源with PATCH

要創建資源，執行"add"操作， "path"指向對應資源集合的末尾 ("/-")。"value"必須包含一個資源對象。

比如，新photo通過如下請求創建：

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

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

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

PATCH /photos/1

Content-Type: application/json-patch+json

[

{

"op": "replace",

"path": "/src",

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

}

]

更新關聯with PATCH

要更新關聯，向對應的關聯URL發出合適的PATCH操作即可。

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

關聯更新with PATCH

要更新單對象關聯，對指向關聯的URL和"path" 執行"replace"操作。

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

PATCH /article/1/links/author

Content-Type: application/json-patch+json

[

{

"op": "replace",

"path": "/",

"value": "1"

}

]

要移除單對象關聯，對關聯執行remove操作。例如：

PATCH /article/1/links/author

Content-Type: application/json-patch+json

[

{

"op": "remove",

"path": "/"

}

]

更新多對象關聯 with PATCH

盡管在GET響應中，多對象關聯以JSON數組形式表示，但是更新時更像是集合。

要添加元素到多對象關聯，執行指向關聯URL的"add" 請求。由于操作指向集合末尾， "path" 必須以"/-"結尾。

例如，考慮下面的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請求執行add操作，即可將comment 30 轉移到這個photo。

PATCH /photos/1/links/comments

Content-Type: application/json-patch+json

[

{

"op": "add",

"path": "/-",

"value": "30"

}

]

要移除多對象關聯，對指向關聯對象的URL執行"remove"操作。因為操作目標是元素集合，"path"必須以"/"結尾。

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

PATCH /photos/1/links/comments

Content-Type: application/json-patch+json

[

{

"op": "remove",

"path": "/5"

}

]

刪除資源with PATCH

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

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

PATCH /photos/1

Content-Type: application/json-patch+json

Accept: application/vnd.api+json

[

{

"op": "remove",

"path": "/"

}

]

響應

204 No Content

若PATCH請求成功，客戶端當前的屬性保持最新，服務器必須響應204 No Content 狀態碼。

200 OK

如果服務器接受更新，但是在請求指定內容之外做了資源修改，必須響應200 OK以及更新的資源實例。

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

例如，一個請求以分離操作，創建兩個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"

}

}

]

響應內容在數組中包含對應的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"

}]

}

]

其它響應

當服務器執行PATCH請求時出現一個或多個問題，應該在響應中指定最合適的HTTP狀態碼。客戶端依據HTTP規范解析錯誤。

服務器可以選擇在第一個問題出現時，立刻終止PATCH 操作，或者繼續執行，遇到多個問題。例如，服務器可能多屬性更新，然后返回在一個響應里返回多個校驗問題。

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

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

HTTP 緩存

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

總結

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

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。