返回首页 用 JSON 构建 API 的标准指南
FAQ

资源获取

资源,或者资源集合,通过向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

若没有指定类型对象的字段,或者后端不支持fieldfields[TYPE]参数,后端会默认返回资源对象的所有字段。

后端可以选择总是返回有限的,未指定的字段集,例如id or href.

注意: fieldsfields[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

如果没有指定排序方式,或者后端不支持sortsort[TYPE],后端将会返回使用重复算法排序的资源对象。换言之,资源应该总是以相同顺序返回,即使排序规则没有指定。

注意:sortsort[TYPE]不能混用。如果使用后者,必须与主要资源一同使用。

上一篇: URLs 下一篇: 创建,更新,删除...