文档中心

Appearance

IoT 业务中心 RESTful API 指南 ​

本指南定义了移动应用客户端（Android / iOS）及管理控制台（Web）与设备业务中心交互的 RESTful API 规范。所有接口均要求通过 HTTPS 协议进行安全通信。

1. 架构拓扑与交互流向 ​

当客户端请求设备业务中心的 RESTful 接口时，由 API 网关统一处理身份校验（JWT）、流量限制（X-RateLimit）和请求路由。

mermaid
sequenceDiagram
    participant Client as 客户端 (Web / App)
    participant Gateway as API 网关
    participant Auth as 身份鉴权中心 (Auth)
    participant Core as 业务后台 (Core)
    
    Client->>Gateway: 发起 API 请求 (携带 Bearer Token)
    Gateway->>Auth: 验证 Access Token
    alt Token 验证成功
        Auth-->>Gateway: 校验通过 (包含 User & Scope 元数据)
        Gateway->>Gateway: 限流检测 (X-RateLimit)
        alt 频次未超限
            Gateway->>Core: 路由转发请求
            Core-->>Gateway: 返回业务响应数据 (JSON)
            Gateway-->>Client: 200 OK (携带 X-RateLimit-* 头)
        else 频次超限 (Rate Limit Exceeded)
            Gateway-->>Client: 429 Too Many Requests (携带 RFC 7807 结构)
        end
    else Token 失效/过期
        Auth-->>Gateway: 验证失败 (Expired / Invalid)
        Gateway-->>Client: 401 Unauthorized (提示刷新 Token)
    end

2. 基础信息 ​

2.1 根路径 (Base URL) ​

生产环境 API 服务的统一入口为：

http
https://api.example.com/v1

注意：所有请求必须使用 HTTPS 强加密协议，任何 HTTP 请求都将被 301 重定向至 HTTPS。

2.2 字符编码与格式 ​

  • 通信格式: 统一采用 application/json。
  • 字符集: UTF-8。
  • 时间戳格式: 采用 Unix 时间戳格式（单位：毫秒，如 1716000000000）。

3. 安全与身份验证 (JWT) ​

系统使用 JSON Web Token (JWT) 作为请求凭证。客户端在登录成功后将获得一组 Token。

3.1 令牌机制 ​

  1. Access Token: 访问令牌，用于访问所有受保护资源。
    • 有效期: 2 小时。
    • 请求携带方式: 在 HTTP 头部注入 Authorization。
      http
      Authorization: Bearer <access_token>
  2. Refresh Token: 刷新令牌，用于当 Access Token 过期时换取新令牌。
    • 有效期: 7 天。
    • 更新方式: 客户端通过调用 POST /v1/auth/refresh 接口换取，无需用户重新输入密码。

4. 并发限制 (Rate Limiting) ​

为了防御恶意攻击并防止接口被大流量压垮，网关针对客户端凭证（Token）及 IP 地址实施严格的限流。

4.1 限流响应头 (Rate Limit Headers) ​

网关会在每个 API 请求的响应中携带以下头部，以便客户端根据频次自调整：

响应头数据类型描述
X-RateLimit-LimitInteger当前接口允许的最大请求频率（单位：次/分钟）
X-RateLimit-RemainingInteger当前时间窗口内剩余可用的请求次数
X-RateLimit-ResetInteger限制重置的 Unix 时间戳（单位：秒）

4.2 触发限流 ​

当请求超过频次上限时，API 将直接拒绝连接，返回 429 Too Many Requests 状态码，并在响应头中包含：

http
Retry-After: 35

提示：Retry-After 指明客户端需要等待的秒数（如 35 秒）方可发起下一次请求。

5. 统一异常规范 (RFC 7807) ​

为了提供更细致的故障排查信息，我们遵循 RFC 7807 (Problem Details for HTTP APIs) 规范。对于所有 4xx / 5xx 错误响应，Content-Type 统一设为 application/problem+json，响应体包含以下结构：

json
{
  "type": "https://api.example.com/errors/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Your current request rate exceeds the allocated limit of 100 requests per minute.",
  "instance": "/v1/devices"
}

5.1 字段描述 ​

  • type (string): 错误类型的唯一 URI 地址，指向关于此错误的开发者文档。
  • title (string): 简短且易懂的错误说明（通常与 HTTP 状态码短语一致）。
  • status (integer): 此次错误的 HTTP 状态码。
  • detail (string): 具体的故障排查提示，解释为什么出错以及如何纠正。
  • instance (string): 发生此次错误的 API 请求路径。