一、接口文档概述
本文档定义系统对外提供的RESTful API接口规范,适用于Web/移动端/第三方系统对接。所有接口采用UTF-8编码,遵循JSON数据格式。
二、请求规范
1. 请求方法
- GET:获取资源列表/单个资源
- POST:创建新资源
- PUT:更新完整资源
- PATCH:部分更新资源
- DELETE:删除资源
2. URL结构
示例:/api/v1/{资源路径}
版本号强制包含在URL路径中
3. 请求头部
必含字段:
- Content-Type: application/json
- Authorization: Bearer {access_token}
4. 请求参数
参数位置支持:URL Query/Path Params/Request Body
示例(用户登录接口):
参数名称:username
类型:string
必填:是
描述:用户账号
三、响应规范
1. 状态码
200:请求成功
201:资源创建成功
400:客户端请求错误
401:未授权访问
404:资源不存在
500:服务器内部错误
2. 响应结构
统一返回格式:
{
"code" : 200,
"data" : {},
"message" : "success"
}
四、错误码定义
1001:参数校验失败
1002:资源不存在
1003:权限不足
1004:请求频率超限
1005:token过期
1006:数据格式错误
五、接口示例
1. 用户登录接口
请求方法:POST
请求地址:/api/v1/auth/login
请求参数:
- username: string
- password: string
响应示例:
{
"code": 200,
"data": {
"user_id": "U123456",
"access_token": "xxxxxx"
}
}
2. 商品查询接口
请求方法:GET
请求地址:/api/v1/products
请求参数:
- page: integer (默认1)
- page_size: integer (默认20)
响应示例:
{
"code": 200,
"data": {
"total": 100,
"items": [{
"product_id": "P789",
"price": 99.99
}]
}
}
六、SDK使用规范
1. SDK安装
支持语言:Python/Java/Node.js
Python安装命令:
pip install ecommerce-sdk
2. 初始化配置
示例代码:
sdk = EcommerceClient(
app_id="your_app_id",
secret_key="your_secret_key"
)
3. 方法调用
示例:
response = sdk.user.get_profile(user_id="U123")
七、安全规范
1. 所有请求必须携带HTTPS协议
2. 敏感字段需使用AES-256加密传输
3. 接口调用频率限制:单IP 100次/分钟



.jpg)
.jpg)