RESTful API 设计规范速查表
RESTful 是 Web API 的主流设计风格，整理设计规范和最佳实践，快速构建标准 API。
返回 参考手册URL 设计规范 5
/api/v1/users资源集合（复数名词）
/api/v1/users/123单个资源（ID 定位）
/api/v1/users/123/orders子资源嵌套
/api/v1/users?role=admin查询参数过滤
/api/v1/users?page=2&limit=20分页参数
HTTP 方法 6
GET /users获取资源列表
GET /users/123获取单个资源
POST /users创建资源
PUT /users/123完整更新资源
PATCH /users/123部分更新资源
DELETE /users/123删除资源
常用状态码 8
200 OK请求成功
201 Created创建成功
204 No Content成功但无返回内容
400 Bad Request请求参数错误
401 Unauthorized未认证
403 Forbidden无权限
404 Not Found资源不存在
500 Internal Server Error服务器内部错误
响应格式 4
{ "data": {...}, "meta": {...} }标准响应结构
{ "error": { "code": "INVALID", "message": "..." } }错误响应结构
Content-Type: application/jsonJSON 响应头
X-Total-Count: 100分页总数头
💡 提示
- URL 使用名词复数表示资源集合，如 /users 而不是 /user。
- GET 请求应该是安全的，不改变服务器状态。
- PUT 是完整替换，PATCH 是部分更新，根据场景选择。
- API 版本放在 URL 路径中（/v1/）或请求头中（Accept-Version）。