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

读取。
示例：

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}的车队