Holdingbyte

Appearance

开放接口文档 ​

开放接口提供了为设备、因子、数据的 RESTful 接口，方便你快速搭建物联网应用。

你也可以直接进入设备管理平台，管理你的设备、因子等。

API 基础信息 ​

  • 基础域名：https://ums.holdingbyte.com
  • API 版本：v2
  • 基础路径：/api/v2/

例如，完整的设备列表接口地址为：https://ums.holdingbyte.com/api/v2/devices/

文档结构 ​

请求格式 ​

所有请求都应该是 JSON 格式，请在请求头中设置：

Content-Type: application/json

Token 认证 ​

API 支持 token 认证方式，适用于第三方应用或自动化脚本访问 API。需要在请求头中添加 Token：

http
Authorization: Bearer YOUR_ACCESS_TOKEN

注意事项：

  • Token 必须是有效的且未过期
  • Token 必须属于激活状态（is_active=true）
  • Token 关联的组织必须有效
  • 如果 Token 设置了过期时间（expires_at），则必须在有效期内

您可以在设备管理平台中管理 Token。

响应格式 ​

所有响应都是 JSON 格式，采用统一的响应结构：

成功响应 ​

当请求成功时（HTTP 状态码 200），返回格式如下：

json
{
    "success": true,
    "data": {
        // 响应数据
    },
    "error": null
}

对于列表数据，返回格式如下：

json
{
    "success": true,
    "data": {
        "count": 100,
        "next": "https://ums.holdingbyte.com/api/v2/devices/?page=2",
        "previous": null,
        "results": [
            // 数据列表
        ]
    },
    "error": null
}

错误响应 ​

当请求失败时（HTTP 状态码非 200），返回格式如下：

json
{
    "success": false,
    "data": null,
    "error": {
        "code": "ERROR_CODE",
        "message": "错误信息"
    }
}

常见状态码：

  • 200：请求成功
  • 400：请求参数错误
  • 401：未认证
  • 403：无权限
  • 404：资源不存在
  • 500：服务器内部错误

分页 ​

列表接口支持分页，分页参数：

  • page: 页码，默认为 1
  • page_size: 每页数量，默认为 20

过滤和排序 ​

大部分列表接口支持过滤和排序：

  • 过滤：使用相应的查询参数
  • 排序：使用 ordering 参数，例如 ?ordering=-created_at

请求限制 ​

  • API 采用限流机制，请合理控制请求频率
  • 单个请求体大小限制为 10MB
  • 文件上传大小限制为 50MB