用途:帮助设计一致、规范的 RESTful API,包含版本管理、文档与错误处理。
主要能力:
- RESTful 约定:GET /users 列表(200+数组)、GET /users/:id 获取单个(200/404)、POST /users 创建(201+创建结果)、PUT /users/:id 替换(200/404)、PATCH /users/:id 更新(200/404)、DELETE /users/:id 删除(204/404);嵌套如 GET /users/:userId/orders。
- 命名:资源用复数名词(/users、/orders);查询参数用 snake_case(page_size);请求/响应体用 camelCase;版本推荐 URL 路径 /api/v1/...。
- 响应格式:成功 { "data": {...}, "meta": {...} };列表在 meta 中加 { page, pageSize, total, totalPages };错误 { "error": { "code": "VALIDATION_ERROR", "message": "...", "fields": {...} } }。
- 状态码:200 成功 GET/PUT/PATCH;201 成功 POST;204 成功 DELETE;400/422 无效输入/校验失败;401/403 未认证/无权限;404/409 未找到/冲突;429 限流;500 意外错误。
- 分页:偏移 ?page=2&page_size=20(简单,大数据集慢);游标 ?cursor=abc&limit=20(一致、快、不支持跳页)。
- 过滤与排序:GET /users?status=active&sort=created_at:desc&q=john&page=1&page_size=20。
使用方式:按工作流执行——定义资源与关系、选择版本策略、用 RESTful 命名定义端点、指定响应/错误结构、加分页过滤排序、用 OpenAPI 编写文档、添加限流响应头。
适用场景:需要统一 API 设计规范、错误结构与文档的项目。
限制:资料未提供具体安装命令、收费、平台或效果信息;相关规则文件包括 rules/agent/api-design-rules.md、rules/core/simplicity-over-complexity.md、rules/agent/structured-data-schema.md、rules/agent/error-handling-standard.md。