openclaw restful接口规范严格遵循richardson成熟度模型第3级，涵盖资源化url设计、http方法语义化、标准状态码、路径式版本控制及解耦响应体五方面要求。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用OpenClaw构建对外服务接口时发现路由混乱、状态码语义模糊或客户端难以理解资源操作逻辑，则很可能是未严格遵循RESTful设计规范。以下是依据OpenClaw工程实践提炼出的RESTful接口规范要点，重点结合Richardson成熟度模型进行对照说明：
一、以资源为中心的URL设计
OpenClaw RESTful接口将设备连接、规则配置、流数据等实体抽象为可寻址资源，所有路径必须使用复数名词且不包含动词。该设计直接对应Richardson成熟度模型第3级（HATEOAS预备级）的核心要求，即通过统一资源标识符（URI）表达资源集合与实例，使客户端仅依赖HTTP方法即可推断操作意图。
1、将规则配置资源定义为/api/v1/rules，而非/getRuleConfigs或/createRule等动词路径。
2、对单个规则的操作通过路径参数定位：/api/v1/rules/{id}，其中{id}为规则唯一标识符。
3、禁止在查询字符串中传递操作语义，例如/deleteRule?id=123属于模型第1级（纯HTTP传输），不符合OpenClaw推荐的第3级规范。
二、HTTP方法语义化约束
OpenClaw强制要求使用标准HTTP方法表达资源生命周期操作，杜绝滥用POST承载全部行为。此做法完全契合Richardson模型第2级（资源导向）到第3级（超媒体控制）的跃迁路径，确保接口具备天然幂等性与可缓存性，降低高并发场景下的重试风险。
1、使用GET /api/v1/rules获取规则列表，该请求天然幂等且可被代理缓存。
2、使用POST /api/v1/rules创建新规则，明确标识非幂等操作，触发服务端生成新资源并返回201 Created及Location头。
3、使用PUT /api/v1/rules/{id}全量更新指定规则，要求客户端提供完整资源表示，符合幂等性契约。
4、使用DELETE /api/v1/rules/{id}移除规则，响应204 No Content表示资源已销毁。
三、状态码与错误体标准化
OpenClaw拒绝将所有响应统一封装为200 OK并在Body中自定义错误码，而是严格采用RFC 7231定义的HTTP状态码传达操作结果。该实践达到Richardson模型第3级对“标准协议语义”的完整采纳，使客户端无需解析响应体即可判断请求成败。
使用聊天补全、重试、结构化输出和明确的 User-Agent 标头运行 AIMLAPI LLM 与推理工作流，适用于 Codex 对 AIMLAPI 模型进行脚本化提示/推理调用的场景。
1、成功创建资源时返回201 Created，而非200 OK加自定义{"code":0,"msg":"success"}结构。
2、资源未找到时返回404 Not Found，禁止用200 OK配合{"code":404,"msg":"rule not exist"}模拟语义。
3、客户端请求体格式错误时返回400 Bad Request，并在响应体中提供application/problem+json格式的机器可读错误详情。
四、版本控制与演进隔离
OpenClaw将API版本号显式置于URL路径中（如/api/v1/），而非依赖请求头或查询参数。该策略满足Richardson模型第3级对“长期兼容性”的支撑需求，为底层OpenClaw协议重构提供缓冲空间，避免因框架升级导致客户端大规模适配。
1、新功能发布时启用/api/v2/路径，旧版本/api/v1/保持至少12个月向后兼容。
2、禁止通过Accept: application/vnd.openclaw.v2+json等媒体类型协商版本，因其增加客户端实现复杂度且不利于CDN缓存识别。
3、所有文档与SDK生成器均以路径版本为基准生成对应契约，确保契约与实现强一致。
五、响应体结构解耦化
OpenClaw严禁将底层C++引擎内部结构体（含指针、文件描述符、状态机标识）直接序列化为JSON返回。该限制源于Richardson模型第3级对“超媒体驱动”的隐含要求——响应体应仅包含客户端可消费的领域资源表示，与服务端实现细节彻底隔离。
1、规则配置响应体仅包含id、name、enabled、last_modified等业务字段，剔除所有内存布局相关属性。
2、嵌入式关联资源（如规则所属设备）通过_links字段提供HAL风格超链接，例如"device": {"href": "/api/v1/devices/abc123"}。
3、批量操作结果统一采用207 Multi-Status响应，每个子资源状态独立编码，避免混合成功与失败时的语义混淆。
