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

读取。

示例：

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