卡布达研发团队

# API 规范

# API 命名规范

  1. 协议 API 与用户的通信协议，总是使用HTTPS (opens new window)协议。

  2. 域名 应该将 API 部署在专用域名之下，为了之后的扩展，添加前缀来区分业务。

https://test.doulaoban.com/api
1
  1. 版本 应该将 API 的版本号放入 URL，来区分接口版本，服务于不同版本的业务。
https://test.doulaoban.com/api/v1
1
  1. 模块名 应该将模块名放入版本号之后，来快速定位接口所属业务模块
// 关于用户的模块
https://test.doulaoban.com/api/v1/user
1
2
  1. 路径 路径又称重点，标识 API 的具体网址。网址中不能有动词(涉及到插入，更新，删除可以有动词)，只能有名词，而且所用的名词往往与数据库表名对应。具体看示例。 正例：
// 查询单个用户的信息，后缀使用info
https://test.doulaoban.com/api/v1/user/user_info

// 查询多个用户的信息，后缀使用list
https://test.doulaoban.com/api/v1/user/user_list

// 获取用户的统计数据，后缀使用count
https://test.doulaoban.com/api/v1/user/user_count

// 新增用户信息，后缀使用create
https://test.doulaoban.com/api/v1/user/user_create

// 修改用户信息，后缀使用update
https://test.doulaoban.com/api/v1/user/user_update

// 删除用户信息，后缀使用delete
https://test.doulaoban.com/api/v1/user/user_delete
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
  1. 过滤信息 如果记录数量很多，服务器不可能将他们全部返回用户。API 提供参数，过滤返回结果。
// 指定返回10个用户数据，参数名limit
https://test.doulaoban.com/api/v1/user/users_list?limit=10

// 分页返回用户数据，页码page,分页大小paginate
https://test.doulaoban.com/api/v1/user/users_list?page=1&paginate=10

// 根据已绑定的抖音号数量对用户进行倒序，排序字段order_key,排序order_value
https://test.doulaoban.com/api/v1/user/users_list?order_key=dy_number&order_value=desc
1
2
3
4
5
6
7
8
9

# API Header 自定义参数命名规范

  1. 需要自定义 header 头参数时，参数名必须使用前缀，使用—来链接参数单词，每个单词首字母必须大写，区分项目或服务。

    • 正例：D-Version 抖老板服务版本
    • X-Version 选品服务版本

← Git 规范 →