RESTful API 设计规范指南

核心原则

RESTful API 遵循资源导向设计，使用标准 HTTP 方法操作资源。

HTTP 方法语义

URL 设计规范

GET    /api/users          # 获取用户列表
GET    /api/users/123      # 获取特定用户
POST   /api/users          # 创建新用户
PUT    /api/users/123      # 更新用户
DELETE /api/users/123      # 删除用户

状态码使用

• 200 OK：成功
• 201 Created：资源创建成功
• 400 Bad Request：请求参数错误
• 401 Unauthorized：未授权
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

版本控制

使用 URL 前缀：/api/v1/users