3. RESTful API 设计原则

在低延迟模型服务场景中，RESTful API 是模型推理端点与客户端之间的核心契约。良好的 REST 设计不仅降低集成成本，还直接影响服务可观测性与版本演进能力。本节从架构风格、资源定义、HTTP 方法、状态码与版本管理五个维度展开。

3.1 REST 架构风格与约束

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，由 Roy Fielding 在 2000 年提出。一个符合 REST 原则的 API 必须满足以下六项约束：

3.2 资源定义与 URI 设计

在 REST 中，资源是 API 的核心抽象。模型服务中的资源通常包括：模型、模型版本、推理任务、批量任务、模型元数据等。URI 设计应遵循名词复数形式，避免动词。

3.3 HTTP 方法映射

标准 HTTP 方法对应 CRUD 操作。模型服务 API 的方法映射如下：

3.4 状态码设计

正确的状态码让客户端无需解析响应体即可判断请求结果。模型服务 API 应遵循以下状态码规范：

3.5 API 版本管理

模型服务 API 的版本管理策略直接影响客户端兼容性与迭代效率。主流方案有三种：

3.6 模型服务 API 完整示例

以下是一个符合 REST 原则的模型推理 API 请求与响应示例：

POST /api/v1/models/sentiment-v2/predict HTTP/1.1
Host: inference.example.com
Authorization: Bearer sk-xxxxxxxxxxxx
Content-Type: application/json
X-Request-ID: req-20250321-001

{
  "text": "今天天气真好，心情非常愉快！",
  "options": {
    "return_probabilities": true,
    "max_length": 128
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: req-20250321-001
X-Model-Version: 2.3.1
X-Inference-Time-MS: 42

{
  "label": "positive",
  "probability": 0.987,
  "confidence": 0.95,
  "latency_ms": 42
}