2. OpenAPI 基础概念：RESTful API 风格、HTTP 方法与状态码

在任务调度平台中，所有对外提供的功能——创建任务、查询执行记录、暂停调度、删除触发器——都是通过 OpenAPI 暴露的。理解 OpenAPI 的底层通信规范，是调试接口和修复错误的前提。本章聚焦三个核心概念：RESTful API 风格、HTTP 方法 与 状态码含义。

2.1 RESTful API 风格

REST（Representational State Transfer）是一种架构风格，而非协议。任务调度平台的 OpenAPI 遵循 RESTful 约束，核心原则包括：

• 资源导向：每个 URL 代表一个资源（如 /api/jobs 代表任务集合，/api/jobs/123 代表单个任务）。
• 无状态：每次请求包含所有必要信息，服务端不保存客户端上下文。
• 统一接口：通过固定的 HTTP 方法操作资源。
• 可缓存：响应可被客户端或中间代理缓存（通常用于 GET 请求）。

2.2 HTTP 方法（GET / POST / PUT / DELETE）

任务调度平台的 OpenAPI 使用四种主要 HTTP 方法对应 CRUD 操作。下表列出每种方法在调度场景中的典型用途：

2.2.1 方法使用示例

以下代码展示使用 cURL 调用调度平台 OpenAPI 的四种典型场景：

# 1. GET：查询所有运行中的任务
curl -X GET "https://api.scheduler.example.com/v1/jobs?status=running" \
  -H "Authorization: Bearer <token>"

# 2. POST：创建一个新的定时任务
curl -X POST "https://api.scheduler.example.com/v1/jobs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "数据同步任务",
    "cron": "0 0/30 * * * ?",
    "type": "HTTP",
    "endpoint": "https://internal.service/sync"
  }'

# 3. PUT：更新任务配置（全量替换）
curl -X PUT "https://api.scheduler.example.com/v1/jobs/job-001" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "数据同步任务-更新版",
    "cron": "0 0 * * * ?",
    "type": "HTTP",
    "endpoint": "https://internal.service/sync-v2",
    "timeout": 30000
  }'

# 4. DELETE：删除任务
curl -X DELETE "https://api.scheduler.example.com/v1/jobs/job-001" \
  -H "Authorization: Bearer <token>"

2.3 HTTP 状态码含义

服务端通过状态码告知客户端请求结果。在任务调度平台调试中，以下状态码出现频率最高：

2.4 常见错误与修复对照

结合 RESTful 风格、HTTP 方法和状态码，下表列出任务调度平台调试中最常见的三类错误及修复方案：