4. RESTful API 设计原则：资源命名规范、URL设计、版本控制、无状态特性、使用JSON作为数据交换格式

在物联网采集平台中，HTTP API 是设备与平台、平台与上层应用之间的核心通信契约。遵循 RESTful 设计原则能够确保 API 的可读性、可维护性和可扩展性。本章将围绕资源命名、URL 结构、版本控制、无状态约束以及数据格式五个关键维度展开，为后续的接口实现奠定规范基础。

4.1 资源命名规范

RESTful 架构将一切视为“资源”（Resource），每个资源通过唯一的 URI 标识。命名规范直接影响 API 的易用性与一致性。

4.2 URL 设计模式

URL 是资源的地址，设计时应兼顾可读性与查询效率。以下为物联网采集平台的典型 URL 模式：

# 资源集合
GET    /devices                     # 获取设备列表
POST   /devices                     # 创建设备

# 单个资源
GET    /devices/{deviceId}          # 获取指定设备
PUT    /devices/{deviceId}          # 更新设备
DELETE /devices/{deviceId}          # 删除设备

# 子资源（从属关系）
GET    /devices/{deviceId}/sensors  # 获取某设备下的传感器列表
POST   /devices/{deviceId}/sensors  # 为该设备添加传感器

# 子资源实例
GET    /devices/{deviceId}/sensors/{sensorId}          # 获取指定传感器
GET    /devices/{deviceId}/sensors/{sensorId}/telemetry # 获取传感器遥测数据

# 查询参数（过滤、排序、分页）
GET    /devices?status=active&page=1&size=20
GET    /telemetry?from=2025-01-01&to=2025-01-31&sort=timestamp,desc

4.3 版本控制

API 版本控制是保障向后兼容性的核心手段。物联网平台通常面临设备固件升级滞后、多版本客户端共存等挑战，合理的版本策略至关重要。

4.4 无状态特性

RESTful API 要求服务器不保存客户端请求之间的任何上下文（Session）。每个请求必须包含服务器处理该请求所需的全部信息。

• 认证信息：每个请求携带 Token 或 API Key，不依赖服务器 Session。
• 上下文数据：分页、排序、过滤参数全部通过请求参数传递。
• 幂等性：同一请求重复执行应产生相同结果（GET、PUT、DELETE 天然幂等）。
• 水平扩展：无状态设计使得任意服务器实例均可处理任意请求，无需 Session 同步。

4.5 使用 JSON 作为数据交换格式

JSON（JavaScript Object Notation）因其轻量、易读、跨语言支持广泛，已成为 RESTful API 的事实标准数据格式。物联网平台中，JSON 用于设备上报、指令下发、配置同步等所有数据交互。

以下为物联网采集平台中典型的 JSON 数据模型示例：

// 设备上报遥测数据
POST /api/v1/devices/{deviceId}/telemetry
Content-Type: application/json

{
  "deviceId": "sensor-001",
  "timestamp": "2025-03-21T14:30:00Z",
  "measurements": {
    "temperature": 23.5,
    "humidity": 68.2,
    "pressure": 1013.25
  },
  "metadata": {
    "firmwareVersion": "2.1.0",
    "batteryLevel": 85
  }
}

// 平台下发指令
POST /api/v1/devices/{deviceId}/commands
Content-Type: application/json

{
  "commandId": "cmd-20250321-001",
  "type": "setThreshold",
  "parameters": {
    "sensor": "temperature",
    "min": 10.0,
    "max": 40.0
  },
  "expiry": "2025-03-21T15:00:00Z"
}

4.6 综合设计示例

以下为一个完整的物联网采集平台 API 端点设计清单，综合应用上述五项原则：