资源获取
资源,或者资源集合,通过向URL发出GET
请求获取。
响应内容可以使用如下所示的特点,进一步细化。
过滤
服务器可以选择性支持,依据指定标准进行资源过滤。
通过向资源集合的基准URL添加过滤参数,来支持资源过滤。
例如,下面是请求与特定post关联的所有comments:
GET /comments?posts=1
使用这种方案,单一请求可以使用多过滤器:
GET /comments?posts=1&author=12
这种规范仅支持基于严格匹配的资源过滤。API允许使用的额外过滤器应该在它的侧写中指定。
内链资源
服务器可以选择性支持,返回包含主要资源和链接资源对象的复合文档。
默认情况下,后端返回链接主要资源的资源对象。
后端也可以基于请求中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]
不能混用。如果使用后者,必须与主要资源一同使用。