# 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   | 资源不存在   | 请求的资源不存在             |