面向资源设计的HTTP APIs中,绝大部分的操作都是CRUD(Create,Read,Update,Delete)
,都可以映射为某一个HTTP Method。其余的无法映射的操作一般存在两种解决方案:
- 抽象出新的资源,比如
禁用用户
的操作。假设用户的资源是/user
,那么可以抽象出来一个被锁定的用户的资源/user/disabled
。如此以来,禁用用户
:POST /user/disabled
或者PUT /user/disabled/{user_id}
。取消禁用
:DELETE /user/disabled/{user_id}
。获取被禁用的用户列表
:GET /user/disabled
。
- 如果上面的方式无法满足需要,则可以采用
POST
和URL/动词
的组合。还拿上面的举例:禁用用户
:POST /user/{user_id}/disable
或者PUT /user/{user_id}/disable
。取消禁用
:DELETE /user/{user_id}/disable
。获取被禁用的用户列表
:GET /user?status=DISABLED
。
每一个HTTP Method
都具有一下两个HTTP协议层面的语义。
HTTP 语义 | 含义 |
---|---|
安全 | 操作不会对资源产生副作用,不会修改资源。 |
幂等 | 执行一次和重复执行N次,结果是一样的。 |
HTTP Method | 安全 | 幂等 | 描述说明 |
---|---|---|---|
GET | ✔ | ✔ | 获取一个资源 |
PUT | ✘ | ✔ | 更新或创建一个资源(完整替换) |
PATCH | ✘ | ✘ | 更新一个资源(部分更新) |
DELETE | ✘ | ✔ | 删除一个资源 |
POST | ✘ | ✘ | 创建,或者不满足以上四个Method语义的所有操作 |
PATCH
和POST
都是不安全
且不幂等
的,差异在于PATCH
仅是用于部分更新资源。PATCH
是一个可选支持的HTTP Method
,可能会存在一些代理、网关等组件不支持的情况,所以推荐用POST
来代替它。