mirror of https://github.com/allinssl/allinssl
97 lines
4.8 KiB
Markdown
97 lines
4.8 KiB
Markdown
# API格式和规范
|
||
|
||
## 一、总体说明
|
||
|
||
### 1.1 文档目的
|
||
|
||
本文档旨在规范域名注册平台前后端接口对接标准，为前端开发人员和后端开发人员提供清晰的接口规范和调用指南，确保开发过程中的顺畅协作。
|
||
|
||
### 1.2 接口规范概述
|
||
|
||
域名注册平台统一使用POST请求方式，接口返回JSON格式数据。所有接口均需遵循本文档规定的格式和规范。
|
||
|
||
| PS：后端会严格验证参数的字段格式及其数据类型，请严格按要求传递参数 |
|
||
| ------------------------------------------------------------------ |
|
||
|
||
#### 1.2.1 接口路径规则
|
||
|
||
接口路径设计遵循以下两种格式规则，与后端代码结构保持一致：
|
||
|
||
1. 标准模块接口：当服务文件直接位于模块目录下时
|
||
|
||
| Plain Text<br/>/api/v1/{模块}/{功能函数} |
|
||
| ---------------------------------------- |
|
||
|
||
示例：
|
||
|
||
- 后端文件：service/admin/admin_service.py 中的 check 函数
|
||
- 对应接口：/api/v1/admin/check
|
||
|
||
2. 子模块接口：当服务文件位于模块的子目录下或需要进一步细分功能时
|
||
|
||
| Plain Text<br/>/api/v1/{模块}/{子模块}/{功能函数} |
|
||
| ------------------------------------------------- |
|
||
|
||
示例：
|
||
|
||
- 后端文件：service/admin/config_service.py 中的 check 函数
|
||
- 对应接口：/api/v1/admin/config/check
|
||
|
||
或者
|
||
|
||
- 后端文件：service/domain/registry_service.py 中的 list_registries 函数
|
||
- 对应接口：/api/v1/domain/registry/list_registries
|
||
|
||
### 1.3 通用请求/响应格式
|
||
|
||
#### 请求格式
|
||
|
||
用户密钥：BT_DOMAIN_API_2024_a8f3d9e2c1b7f4a6
|
||
|
||
管理员密钥：BT_ADMIN_API_2024_super_admin_key_9527
|
||
|
||
传参调整为使用 Content-Type: application/json JSON格式传参
|
||
|
||
| JSON<br/>POST /api/v1/{模块}/{功能函数} HTTP/1.1<br/>POST /api/v1/{模块}/{子文件名}/{功能函数} HTTP/1.1<br/>Host: api.domain.example.com<br/>X-API-Key: <br/>X-UID: {用户ID}<br/>Content-Type: application/json<br/><br/>{<br/> "参数1": "值1",<br/> "参数2": "值2",<br/> ...<br/>} |
|
||
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
||
前端格式
|
||
|
||
| JavaScript<br/>Content-Type: application/json<br/>data=JSON.stringify(args)<br/><br/>示例：<br/>let args = {<br/> name:"test",<br/> sex:1<br/>}<br/><br/>let url = '/test/create_user.json'<br/>let query_data = JSON.stringify(args)<br/><br/>post(url,query_data,function(res){<br/> console.log(res)<br/>}) |
|
||
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
||
#### 响应格式
|
||
|
||
| JSON<br/>{<br/> "status": true, // 请求是否成功<br/> "code": 0, // 状态码，0表示成功，其他值表示错误<br/> "message": "操作成功", // 状态描述<br/> "data": { // 返回的数据<br/> "key1": "value1",<br/> "key2": "value2"<br/> },<br/> "timestamp": 1628756942 // 服务器时间戳<br/>} |
|
||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
||
### 1.4 认证与授权机制
|
||
|
||
所有API请求需要包含以下认证信息：
|
||
|
||
| PS：如果没有特别标记，一律需要添加KEY+UID，方便后续溯源 |
|
||
| ------------------------------------------------------- |
|
||
|
||
1. X-API-Key: API密钥，用于验证请求来源的合法性
|
||
|
||
2. X-UID: 用户ID，用于识别请求用户身份
|
||
|
||
管理员接口额外需要：
|
||
|
||
- X-API-Key: 管理员登录后获取的令牌【默认写死】
|
||
|
||
### 1.5 错误码规范
|
||
|
||
| 错误码 | 描述 | 说明 |
|
||
| ------ | ------------ | ---------------------------- |
|
||
| 0 | 成功 | 请求处理成功 |
|
||
| 1001 | 参数错误 | 请求参数不符合要求 |
|
||
| 1002 | 认证失败 | API密钥无效或已过期 |
|
||
| 1003 | 权限不足 | 无权限执行请求的操作 |
|
||
| 2001 | 域名不可用 | 请求的域名已被注册或不可注册 |
|
||
| 2002 | 域名格式错误 | 域名格式不符合规范 |
|
||
| 3001 | 订单创建失败 | 订单创建过程中出现错误 |
|
||
| 3002 | 支付失败 | 支付处理过程中出现错误 |
|
||
| 4001 | 实名认证失败 | 实名认证信息验证失败 |
|
||
| 5001 | 资源不存在 | 请求的资源不存在 |
|