一、接口文档概述

本文档定义系统对外提供的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次/分钟