4.8 KiB

Raw Permalink Blame History

API格式和规范

一、总体说明

1.1 文档目的

本文档旨在规范域名注册平台前后端接口对接标准，为前端开发人员和后端开发人员提供清晰的接口规范和调用指南，确保开发过程中的顺畅协作。

1.2 接口规范概述

域名注册平台统一使用POST请求方式，接口返回JSON格式数据。所有接口均需遵循本文档规定的格式和规范。

PS：后端会严格验证参数的字段格式及其数据类型，请严格按要求传递参数

1.2.1 接口路径规则

接口路径设计遵循以下两种格式规则，与后端代码结构保持一致：

标准模块接口：当服务文件直接位于模块目录下时

Plain Text /api/v1/{模块}/{功能函数}

示例：

后端文件：service/admin/admin_service.py 中的 check 函数
对应接口：/api/v1/admin/check

子模块接口：当服务文件位于模块的子目录下或需要进一步细分功能时

Plain Text /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 POST /api/v1/{模块}/{功能函数} HTTP/1.1 POST /api/v1/{模块}/{子文件名}/{功能函数} HTTP/1.1 Host: api.domain.example.com X-API-Key: X-UID: {用户ID} Content-Type: application/json { "参数1": "值1", "参数2": "值2", ... }

前端格式

JavaScript Content-Type: application/json data=JSON.stringify(args) 示例： let args = { name:"test", sex:1 } let url = '/test/create_user.json' let query_data = JSON.stringify(args) post(url,query_data,function(res){ console.log(res) })

响应格式

JSON { "status": true, // 请求是否成功 "code": 0, // 状态码，0表示成功，其他值表示错误 "message": "操作成功", // 状态描述 "data": { // 返回的数据 "key1": "value1", "key2": "value2" }, "timestamp": 1628756942 // 服务器时间戳 }

1.4 认证与授权机制

所有API请求需要包含以下认证信息：

PS：如果没有特别标记，一律需要添加KEY+UID，方便后续溯源

X-API-Key: API密钥，用于验证请求来源的合法性
X-UID: 用户ID，用于识别请求用户身份

管理员接口额外需要：

X-API-Key: 管理员登录后获取的令牌【默认写死】

1.5 错误码规范

错误码	描述	说明
0	成功	请求处理成功
1001	参数错误	请求参数不符合要求
1002	认证失败	API密钥无效或已过期
1003	权限不足	无权限执行请求的操作
2001	域名不可用	请求的域名已被注册或不可注册
2002	域名格式错误	域名格式不符合规范
3001	订单创建失败	订单创建过程中出现错误
3002	支付失败	支付处理过程中出现错误
4001	实名认证失败	实名认证信息验证失败
5001	资源不存在	请求的资源不存在

4.8 KiB Raw Permalink Blame History Unescape Escape