RESTful API 设计最佳实践(6)
在本文中,将重点介绍一些实际设计RESTful API的建议,这些API是基于HTTP协议设计的。这些建议是参考网上一些好的资料并结合自己实际经验做了更加细致的分析,个人觉得有不错的参考价值。
一、两个简单的例子
1. 简单资源的CRUD
GET /users - 获取用户列表
GET /users/:id - 获取用户ID号为:id的用户
POST /users - 创建新的用户
PUT /users/:id - 更新用户:id的信息
PATCH /users/:id - 更新:id指向的用户的部分信息
DELETE /users/:id - 删除:id指向的用户
其中,名词“users”用于标定用户集合这一资源;用户ID(:id)用于标定单个用户;用http规范的方法来表达语义。可以看到,变量:id出现在了url中,也就意味着REST服务需要对url进行解析,以获取该变量值。在前一篇博文中,我已经说明了不用PUT来新建资源的理由,因此这里不做展示。
如果换做是RPC实现,可能很简单的全部用POST的方法,然后在body中指定{
:method :get-user :params ["user-id1"]}。
2. 资源关系的API设计
举个例子,一个用户可能有多个朋友,“朋友”就是一种关系,虽然在后台“朋友”和“用户”本身是都是存在一张“用户表”中。此时API设计如下:
GET /users/:id/friends - 获取用户:id的朋友列表
GET /users/:id