RESTful API 设计规范指南

核心原则

资源导向

URL 表示资源，使用名词而非动词。

HTTP 方法语义

• GET: 获取资源
• POST: 创建资源
• PUT: 更新资源
• DELETE: 删除资源

状态码规范

• 200: 成功
• 201: 创建成功
• 400: 请求错误
• 401: 未授权
• 404: 资源不存在
• 500: 服务器错误

URL 设计规范

• 使用小写字母
• 用连字符分隔单词
• 使用复数名词表示资源集合
• 版本号放入 URL 或 Header

响应格式

统一使用 JSON 格式，包含状态、数据、消息字段。

版本控制

在 URL 中包含版本号（/api/v1/）便于迭代和兼容。

设计良好的 API 是优秀产品的基石！