資源獲取

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

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

過濾

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

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

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

GET /comments?posts=1

使用這種方案，單一請(qǐng)求可以使用多過濾器：

GET /comments?posts=1&author=12

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

內(nèi)鏈資源

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

默認(rèn)情況下，后端返回鏈接主要資源的資源對(duì)象。

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

例如，comments可以通過post請(qǐng)求:

GET /posts/1?include=comments

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

GET /posts/1?include=comments.author

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

多鏈接資源可以使用點(diǎn)分隔列表請(qǐng)求：

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

稀疏字段

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

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

GET /people?fields=id,name,age

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

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

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

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

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

排序

服務(wù)器可以選擇性支持，基于特定標(biāo)準(zhǔn)對(duì)資源集合排序。

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

GET /people?sort=age

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

GET /people?sort=age,name

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

GET /posts?sort=-created,title

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

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

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

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

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