输入“/”快速插入内容

API接口规范

整体规范建议采用RESTful方式来实施

1 协议

API与用户的通信协议，总是使用HTTPs协议，确保交互数据的传输安全。​

2 命名规则

2.1 域名

应该尽量将API部署在专用域名之下，例如：

代码块

https://saos-csp-demo-api.prod.k8s.chj.cloud

2.2 版本控制

若接口结构发生变化，部分下游系统不能及时调整，应采用多版本并存，增量发布的方式。​

应该将API的版本号放入URL，例如：

代码块

https://saos-csp-demo-api.prod.k8s.chj.cloud/v{n}/

v{n} n代表版本号，分为整形和浮点型

整形的版本号: 大功能版本发布形式；具有当前版本状态下的所有API接口，例如：v1、v2​

浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api，例如：v1.1、v2.2​

2.3 路径规则

路径表示API的具体网址，在RESTful架构中，每个网址代表一种资源（resource），所以资源URI不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。参考：REST资源命名指南

2.3.1 使用“单数”名称表示单个资源

代码块

https://api.example.com/v1/device-management/managed-devices/{device-id}​
https://api.example.com/v1/user-management/users/{id}​
https://api.example.com/v1/user-management/users/admin​

2.3.2 使用“复数”名称表示集合资源原

代码块

https://api.example.com/v1/device-management/managed-devices​
https://api.example.com/v1/user-management/users​
https://api.example.com/v1/user-management/users/{id}/accounts​

2.3.3 使用“动词”表示动作控制

代码块

https://api.example.com/v1/cart-management/users/{id}/cart/checkout​
https://api.example.com/v1/song-management/users/{id}/playlist/play​

2.3.4 其他格式约定

1.
使用一致的资源命名约定和URI格式，以最小化和最大可读性和可维护性。​

2.
正斜杠（/）字符用于URI的路径部分，以指示资源之间的层次关系​

3.
不要在URI中使用尾部正斜杠（/）​

4.
使用连字符（ - ）来提高URI的可读性​

5.
不要使用下划线（_）​

6.
在URI中使用小写字母​

7.
不要使用文件扩展名​

8.
切勿在URI中使用CRUD函数名称​

3 接口请求

3.1 资源路由（建议）

动作	方法	参考示例	控制器方法
获取资源列表	GET	• /photos • /photos/{photo}/comments	index
创建资源（前端）	GET	• /photos/create • /photos/{photo}/comments/create
创建资源	POST	• /photos • /photos/{photo}/comments	store

API接口规范​

API接口规范