RESTful API 规范

RESTful API 规范

URI 设计规范

URI（统一资源标识符）是资源的唯一地址，设计需遵循 “简洁、语义化、可理解” 的原则，避免冗余和歧义：

• 使用名词表示资源：URI 中仅包含资源名，不包含动词，操作类型由 HTTP 方法表示（如用POST /book代替POST /create_book）；
• 嵌套表示从属关系：当资源之间存在父子关系时，用嵌套 URI 表示，避免嵌套过深（建议不超过 3 层），示例：/users/123/orders（用户 123 的所有订单）、/kb/456/documents（知识库 456 的所有文档）；
• 全小写，连字符分隔：URI 中所有字符均为小写，多个单词之间用连字符-分隔（而非下划线），示例：/api/v1/book-chapter（书籍章节资源）；
• 版本化管理：为了兼容旧版本接口，建议在 URI 中添加版本号，示例：/api/v1/book、/api/v2/book，便于接口迭代而不影响旧版本使用；
• 避免冗余参数：将常用的筛选、分页参数放在查询字符串中（如/api/v1/book?page=1&size=10&category=python

标准 示例

操作	HTTP 方法	URI 示例	支持参数	说明
获取所有图书	GET	/api/v1/book	分页、筛选、排序	返回图书列表，支持条件查询
创建新图书	POST	/api/v1/book	图书名称、作者、分类等	请求体传递 JSON 数据，创建单本图书
获取单本图书	GET	/api/v1/book/123	无	根据 ID 返回单本图书的详细信息
全量更新图书	PUT	/api/v1/book/123	图书所有字段	替换图书的全部信息，需传递完整字段
部分更新图书	PATCH	/api/v1/book/123	图书部分字段（如价格）	仅更新指定字段，无需传递完整字段
删除单本图书	DELETE	/api/v1/book/123	无	根据 ID 删除指定图书
获取图书的评论	GET	/api/v1/book/123/comments	分页	嵌套 URI，获取图书 123 的所有评论

参考资料：RESTful API 规范详解