在开发HTTP API的时候,我们一般会按照REST风格来设计,符合REST风格的API也称为RESTful API。
RESTful API的主要规则包括以下几点:
- URI表示资源(名词)
- HTTP请求的方法表示动作,指对资源的操作
标准的RESTful API示例如下:
POST /customers:创建一个消费者
GET /customers:获取消费者列表
GET /customers/{id}:获取某个具体的消费者
PUT /customers/{id}:更新某个具体的消费者信息(全量更新)
PATCH /customers/{id}:更新某个具体的消费者的信息(部分更新)
DELETE /customers/{id}:删除某个具体的消费者
// 有联系的资源之间的处理
GET /customers/{id}/orders:获取某个具体消费者的订单列表
...
由于英语语法的特点和HTTP请求的方法数量的有限,可能存在一些无法覆盖到的部分,如下:
- 非常规动作
- 资源对应的名词形式造成的问题:单复数一致,不可数
- 资源之间的关系是一对一
下面来谈谈上述未覆盖部分及其解决方案。
非常规动作的RESTful API的设计
常规动作有GET,POST,PUT,PATCH和DELETE,也就是所谓的增删改查,但是现实中还有很多非前面提到的动作,如取消操作。
针对非常规动作,解决的方案有两种:
- 动词名词化:将动词转成名词,进而当做前面资源的子资源进行处理
- 自定义方案:使用自定义的规范来支持非常规动作
下面我们以取消订单为例,来看看针对该问题不同方案的实现。
动词名词化
该方案是GitHub在使用中的方案,在开放的API的可以看到。
针对实例的实现如下:
POST /orders/{id}/cancellation
自定义方案
这个Google Could中Could API设计规范中定义的方案,语法为:
https://service.name/v1/some/resource/name:customVerb
针对实例的实现如下:
POST /orders/{id}:cancel
资源对应的名词形式造成的问题的解决
资源对应的名词单复数一致
该情况可按照英语语法使用对应的名词即可,如下:
// 单复数一致
GET /advice
GET /advice/{id}
资源对应的名词为不可数名词
使用可数名词来代替,如news可以用news-items来代替。
资源之间的关系是一对一情况的处理
这种情况可以采用资源对应的名词的单数形式来表示获取一条数据, 该方案也适用于多对一的情况。
例如:用户的购物车数据,每个用户有一个购物车,可以表示如下:
GET /customers/{id}/cart