接口规范
以下是添加了标准状态信息的完整API规范，采用RESTful风格设计:
基础URL
获取信息 [GET]
GET https://fanconn.com/faninfo?module=RK3576&target=Fanconn&product=HYJ&version=1.0.18&platform=DC690V&enable=true&sn=b74e67edc84390cd&wifimac=null&IMEI=null&release=A14
/faninfo后面要带设备信息参数仅限于浏览器预览: https://fanconn.com/faninfo_show.json 仅限于浏览器预览
成功响应(200): 最新版修改日期 2025-07-04 14:00
{
"success": true,
"timestamp": "2025-07-04T14:00:00Z",
"code": "QUERY_SUCCESS",
"message": "信息查询成功",
"data": {
"services": {
"ota": [
{
"base_url": "https://fanconn.com",
"endpoints": {
"info": "/ota/FancInfo.php"
}
},
{
"base_url": "https://ota.fanconn.com",
"endpoints": {
"info": "/ota/FancInfo.php"
}
}
],
"frame": [
{
"base_url": "https://frame.fanconn.com",
"endpoints": {
"tasks": "/get_tasks"
}
}
],
"gallery": [
{
"base_url": "https://gallery.fanconn.com",
"endpoints": {
"static_data": "/FancGallery/GMJ/SC138/DC665/A13/Fanconn/gallery.json",
"album_api": "/api/album_data"
}
}
]
}
}
}
建议: 例如 OTA, 默认读取
系统预设值
对
系统预设服务器 URL 发起 http 请求, 如果请求结果为http 200正常使用预设值如果 1.
系统预设访问异常 (例如无法访问,http 40x,http 50x等错误 ) 则使用https://fanconn.com/faninfo提供的data.services.ota[0].base_url+data.services.ota[0].info
"ota": [{},{},{}]内有多个对象值，用于将来扩展 cdn 功能，可循环请求里面的地址。
参考 URL
- OTA 来自
HYJ-DC690V
- Frame
- gallery
https://gallery.fanconn.com:443/api/album_data?device_id=b74e67edc84390cd
- gallery_static
https://gallery.fanconn.com:443/FancGallery/GMJ/SC138/DC665/A13/Fanconn/gallery.json
- gallery_url
https://gallery.fanconn.com:443/FancGallery/GMJ/SC138/DC665/A13/Fanconn/gallery.json
资源端点
通用响应结构
https://fanconn.com/api/v1/fans
{
"success": boolean,
"timestamp": "ISO8601格式时间",
"code": "业务状态码",
"message": "描述信息",
"data": {}, // 成功时返回的数据
"error": { // 错误时返回的详情
"type": "错误类型",
"details": {}
}
}
获取信息 [GET]
GET /api/v1/fans/{fanId}
成功响应(200):
{
"success": true,
"timestamp": "2025-06-26T10:30:00Z",
"code": "FAN_QUERY_SUCCESS",
"message": "信息查询成功",
"data": {
"ota": "https://fanconn.com/ota/fans/123",
"frame": "",
"gallery": ""
}
}
错误响应(404):
{
"success": false,
"timestamp": "2025-06-26T10:31:00Z",
"code": "FAN_NOT_FOUND",
"message": "指定不存在",
"error": {
"type": "RESOURCE_NOT_FOUND",
"details": {
"fanId": "123"
}
}
}
创建信息 [POST]
POST /api/v1/fans
请求体 - Request Body:
{
"success": true,
"timestamp": "2025-06-26T10:31:00Z",
"code": "FAN_NOT_FOUND",
"message": "指定不存在",
{
"ota": "string",
"frame": "string",
"gallery": "string"
}
}
成功响应(201):
{
"success": true,
"timestamp": "2025-06-26T10:32:00Z",
"code": "FAN_CREATE_SUCCESS",
"message": "创建成功",
"data": {
"fanId": "新创建的ID",
"location": "/api/v1/fans/456"
}
}
验证错误响应(400):
{
"success": false,
"timestamp": "2025-06-26T10:33:00Z",
"code": "INVALID_REQUEST",
"message": "请求参数无效",
"error": {
"type": "VALIDATION_ERROR",
"details": {
"ota": "必须提供有效的OTA链接"
}
}
}
更新信息 [PUT]
PUT /api/v1/fans/{fanId}
请求体 - Request Body:
{
"ota": "string",
"frame": "string",
"gallery": "string"
}
成功响应(200):
{
"success": true,
"timestamp": "2025-06-26T10:34:00Z",
"code": "FAN_UPDATE_SUCCESS",
"message": "信息更新成功",
"data": {
"fanId": "123",
"updatedFields": ["ota", "frame"]
}
}
冲突响应(409):
{
"success": false,
"timestamp": "2025-06-26T10:35:00Z",
"code": "FAN_UPDATE_CONFLICT",
"message": "信息更新冲突",
"error": {
"type": "RESOURCE_CONFLICT",
"details": {
"currentVersion": "2",
"submittedVersion": "1"
}
}
}
删除信息 [DELETE]
DELETE /api/v1/fans/{fanId}
成功响应(204):
No Content
错误响应(403):
{
"success": false,
"timestamp": "2025-06-26T10:36:00Z",
"code": "PERMISSION_DENIED",
"message": "无权删除该信息",
"error": {
"type": "AUTHORIZATION_ERROR",
"details": {
"requiredRole": "ADMIN"
}
}
}
这个规范包含了
-
统一的响应结构
-
标准HTTP状态码
-
业务状态码(code字段)
-
时间戳
-
详细的错误信息
-
成功/失败标识
-
数据隔离(data/error字段)