Restful API

设计

版本号

在 RESTful API 中，API 接口应该尽量兼容之前的版本，所以在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下，我们会在 url 中保留版本号，并同时兼容多个版本。
【GET】 /v1/users/{user_id} // 版本 v1 的查询用户列表的 API 接口
【GET】 /v2/users/{user_id} // 版本 v2 的查询用户列表的 API 接

资源路径

URI只能是名词。
复数进行命名。
下划线来区分多个单词。
/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

请求方式

【GET】 /users # 查询
【POST】 /users # 新建
【PUT】 /users/1001 # 更新用户信息(全部字段)
【PATCH】 /users/1001 # 更新用户信息(部分字段)
【DELETE】 /users/1001 # 删除

查询参数

尽量使用offset（）、 limit、 orderby 公共参数
【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20
【GET】 /{version}/{resources}/{resource_id}?orderby={field} [asc|desc]
【GET】 /{version}/{resources}/{resource_id}?count=[true|false]

响应参数

如果是单条数据，则返回一个对象的 JSON 字符串。
{
“id” : “01234567-89ab-cdef-0123-456789abcdef”,
“name” : “example”,
…
}
如果是列表数据，则返回一个封装的结构体
{
“count”:100,
“items”:[
{
“id” : “01234567-89ab-cdef-0123-456789abcdef”,
“name” : “example”,
…
},
…
]
}