RESTful API设计中常见的问题和解决方案

在开发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：获取某个具体消费者的订单列表
...

RESTful API 设计指南

由于英语语法的特点和HTTP请求的方法数量的有限，可能存在一些无法覆盖到的部分，如下：

• 非常规动作
• 资源对应的名词形式造成的问题：单复数一致，不可数
• 资源之间的关系是一对一

下面来谈谈上述未覆盖部分及其解决方案。

非常规动作的RESTful API的设计

常规动作有GET,POST,PUT,PATCH和DELETE，也就是所谓的增删改查，但是现实中还有很多非前面提到的动作，如取消操作。

针对非常规动作，解决的方案有两种：

• 动词名词化：将动词转成名词，进而当做前面资源的子资源进行处理
• 自定义方案：使用自定义的规范来支持非常规动作

下面我们以取消订单为例，来看看针对该问题不同方案的实现。

动词名词化

该方案是GitHub在使用中的方案，在开放的API的可以看到。

Star a gist

针对实例的实现如下：

POST /orders/{id}/cancellation

自定义方案

这个Google Could中Could API设计规范中定义的方案，语法为：

https://service.name/v1/some/resource/name:customVerb

Custom Methods

针对实例的实现如下：

POST /orders/{id}:cancel

资源对应的名词形式造成的问题的解决

资源对应的名词单复数一致

该情况可按照英语语法使用对应的名词即可，如下:

// 单复数一致
GET /advice  
GET /advice/{id}

资源对应的名词为不可数名词

使用可数名词来代替，如news可以用news-items来代替。

资源之间的关系是一对一情况的处理

这种情况可以采用资源对应的名词的单数形式来表示获取一条数据, 该方案也适用于多对一的情况。

例如：用户的购物车数据，每个用户有一个购物车，可以表示如下：

GET /customers/{id}/cart