介绍
- REST(Representational State Transfe),一种架构设计风格,而不是强制标准,主要用于客户端与服务端接口规范;
- 在现代的软件开发中,RESTful API已经成为应用程序之间通信的重要桥梁,互联网公司也更倾向于实践此风格;
- 核心是面向资源,每个网址代表一种资源(URI),具有解释性;
- 行为(GET / POST / PUT / PATCH / DELETE)与资源(URI)分离,更加轻量;
- 数据描述简单,使⽤JSON、XML、PROTOBUFFER即可全覆盖,主要使⽤JSON;
设计规范
- 安全
API与⽤户的通信协议,⼀般使⽤HTTP协议,更安全情况下使⽤HTTPS;
- 域名
应该尽量将API部署在专⽤域名之下,比如api.example.com
;
- 版本
在每个API对应的URL中,应有⼀个版本号,以便将来服务升级后,所有版本的客户端可以正常使用,例如/api/v1/xxx
;
- 命名
核心是面向资源,每个网址代表一种资源,网址中尽量使用名词,避免动词。
资源对应的是数据库中的集合,所以名词尽量使用复数,除非没有合适的复数形式(如 weather)。
- 请求方式
请求方式 | 示例 | 说明 |
---|---|---|
GET | /teams/{id} | 读取 |
POST | /teams | 新建,通常带有 Body |
PUT | /teams/{id} | 更新,全量更新,通常带有 Body |
PATCH | /teams/{id} | 更新,部分更新,通常带有 Body |
DELETE | /teams/{id} | 删除 |
行业参考
- 佳明接口文档
https://developers.strava.com/playground/#/
最佳实践
GET
读取。
示例:
basic
get /teams # 获取车队列表
get /teams/list # 同上,获取车队列表
get /teams?page=1&size=10&search=武汉 # 分页搜索列表
get /teams/{id} # 获取车队id为{id}的详情
get /teams/{id}/detail # 同上,获取车队id为{id}的详情
get /teams/{id}/members # 获取车队id为{id}下的成员列表
POST
新建。
一个参数可放在路径参数,多个参数必须放到 body 中。
示例:
basic
post /teams/{name} # 新建车队,仅有名称
post /teams # 新建车队
# body
{
"name": "武汉车队",
"number": 8888
}
PUT
更新。
put 通常指全部更新,patch 通常指部分更新,一搬支持 put 即可。
示例:
basic
put /teams/{id} # 修改车队id为{id}的信息
# body
{
"id": 123,
"name": "武汉车队Plus",
"number": 9999
}
DELETE
删除。
示例:
basic
delete /teams/{id} # 删除车队id为{id}的车队