REST
REST全称是Representational State Transfer 表述性状态传递。REST可能是现在最流行的一种Web API。
REST的核心就是资源,一个资源就是可以被标识的实体,它有名称和地址。
REST API就是把数据以资源的形式暴露出来,并使用标准的HTTP方法来代表创建、读取、更新和删除资源等事务。
REST规则和约束:
资源都是URL的一部分,例如/persons
针对每个资源通常都会有两个URL被实现:“/persons”表示资源的集合,“/person/321”表示特定的一个资源
在资源里,使用名词而不是动词,例如 /getUserInfo/123 这就不对了,应该是 /users/123
服务器会返回标准的HTTP状态码,来表示请求成功或者失败,以及原因。通常2xx表示成功,3xx表示资源被移动了,4xx表示客户端引起的错误,5xx表示服务器端引起的错误
HTTP方法
方法表明了要执行的动作,不同的HTTP方法作用于同一个URL上可实现不同的功能:
创建 -- POST
读取 -- GET
整体更新 -- PUT
局部更新 -- PATCH
删除 -- DELETE
主从关系
如果两个资源有主从关系,那么子资源最好不采用顶级资源的URL,而是采用主资源的子资源URL地址。例如Province和City就是主从关系,那么City资源的URL应该是:/provinces/{provinceId}/cities,/provinces/{provinceId}/cities/{cityId}
非CRUD操作
API难免会有一个非CRUD的操作,例如“存档”这个操作。这时候我们可以采取以下几种办法:
把这个动作作为资源的一个字段。例如把“存档”作为输入参数传递到API
作为子资源。例如 /repos/{repoId}/issues/{issueId}/archive
直接使用动词。实在不行了,就用动词吧,例如 /search
排序
通过query参数的方式添加: ?orderby=age