4. HTTP API 设计原则：RESTful API 风格、资源路径设计、请求与响应格式（JSON）

在边缘计算场景中，HTTP API 是设备与云端、设备与边缘网关之间最通用的通信契约。设计良好的 API 能显著降低集成成本、提升可维护性。本章聚焦 RESTful 风格的核心原则，并结合边缘计算的实际约束（低带宽、间歇连接、资源受限）进行讲解。

4.1 RESTful API 核心风格

REST（Representational State Transfer）是一种架构风格，而非协议。其核心约束包括：

• 资源导向：将一切数据或状态抽象为“资源”，通过 URI 唯一标识。
• 无状态通信：每个请求包含所有必要信息，服务器不保存客户端上下文。
• 统一接口：使用标准 HTTP 方法（GET/POST/PUT/PATCH/DELETE）操作资源。
• 自描述消息：通过媒体类型（如 application/json）告知客户端如何解析。

4.2 资源路径设计规范

路径（Endpoint）是资源的地址。遵循以下规则可保证可读性与扩展性：

4.3 请求与响应格式：JSON

JSON（JavaScript Object Notation）是 REST API 的事实标准序列化格式。在边缘计算中，JSON 的灵活性与可读性优于二进制协议（如 Protobuf），但需注意载荷大小。

4.3.1 请求体结构

POST /v1/gateways/edge-01/devices
Content-Type: application/json

{
  "device_id": "sensor-temp-05",
  "type": "temperature",
  "unit": "celsius",
  "location": "line-3-zone-a",
  "tags": ["production", "critical"],
  "enabled": true
}

4.3.2 响应体结构

统一响应格式有助于客户端做通用错误处理：

HTTP/1.1 201 Created
Content-Type: application/json

{
  "status": "success",
  "code": 201,
  "message": "Device created",
  "data": {
    "device_id": "sensor-temp-05",
    "created_at": "2025-03-21T08:30:00Z",
    "api_version": "v1"
  }
}

4.4 RESTful 方法映射与边缘场景

4.5 RESTful 资源模型与边缘拓扑

下图展示了一个典型的边缘计算 REST API 资源层级，从云平台到传感器：

4.6 边缘 API 的 JSON 优化策略

在带宽受限的边缘链路中，JSON 载荷需要做针对性优化：

• 字段名缩写：使用短键名（如 dev_id 代替 device_id），可减少 30%~50% 传输体积。
• 去除冗余字段：响应中省略 null 值字段，客户端按契约自行填充默认值。
• 使用时间戳整数：用 Unix 时间戳（秒级整数）代替 ISO 8601 字符串，节省约 40% 字符。
• 批量操作端点：提供 POST /v1/gateways/{id}/data/batch 一次上报多条传感器数据。

4.7 常见设计反模式