RESTful接口规范参考
介绍
- 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
读取。
示例：
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 中。
示例：
post /teams/{name} # 新建车队，仅有名称post /teams # 新建车队
# body
{
"name": "武汉车队",
"number": 8888
}PUT
更新。
put 通常指全部更新，patch 通常指部分更新，一搬支持 put 即可。
示例：
put /teams/{id} # 修改车队id为{id}的信息
# body
{
"id": 123,
"name": "武汉车队Plus",
"number": 9999
}
DELETE
删除。
示例：
delete /teams/{id} # 删除车队id为{id}的车队