请求设计

1. 动词

GET:   读取(Read)
POST:  新建(Create)
PUT:   更新(Update)
PATCH: 更新(Update),通常是部分更新
DELETE:删除(Delete)


2. 宾语必须是名词

宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。比如,/articles这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。

/getAllCars
/createNewCar
/deleteAllRedCars

既然 URL 是名词,为了统一起见,建议都使用复数。


3. 设计参考

GET    /zoos:列出所有动物园
POST   /zoos:新建一个动物园
GET    /zoos/ID:获取某个指定动物园的信息
PUT    /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
PATCH  /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
DELETE /zoos/ID:删除某个动物园
GET    /zoos/ID/animals:列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物


4. 过滤信息(Filtering)

如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。

下面是一些常见的参数。

?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件

参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。


5. 不符合 CRUD 情况的RESTful API

在实际资源操作中,总会有一些不符合 CRUD(Create-Read-Update-Delete) 的情况,一般有几种处理方法。

1、使用 POST,为需要的动作增加一个 endpoint,使用 POST 来执行动作,比如: POST /resend 重新发送邮件。

2、增加控制参数,添加动作相关的参数,通过修改参数来控制动作。比如一个博客网站,会有把写好的文章“发布”的功能,可以用上面的 POST /articles/{:id}/publish 方法,也可以在文章中增加 published:boolean 字段,发布的时候就是更新该字段 PUT /articles/{:id}?published=true

3、把动作转换成资源,把动作转换成可以执行 CRUD 操作的资源, github 就是用了这种方法。


比如“喜欢”一个 gist,就增加一个 /gists/:id/star 子资源,然后对其进行操作:“喜欢”使用PUT /gists/:id/star,“取消喜欢”使用 DELETE /gists/:id/star。


另外一个例子是 Fork,这也是一个动作,但是在 gist 下面增加 forks资源,就能把动作变成 CRUD 兼容的:POST /gists/:id/forks 可以执行用户 fork 的动作。