RESTful API Cheatsheet - REST API Design Reference
RESTful API 接口设计必备规范速查表，从 URL 命名到状态码选择全系列整理，设计 Web API 时直接查。
Back to ReferenceURL 设计规范 6
/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分页参数
/api/v1/users?sort=-created_at排序（- 表示降序）
HTTP 方法 8
GET /users获取资源列表（安全、幂等）
GET /users/123获取单个资源
POST /users创建资源（非幂等）
PUT /users/123完整更新资源（幂等）
PATCH /users/123部分更新资源
DELETE /users/123删除资源（幂等）
HEAD /users/123只获取响应头，不返回 body
OPTIONS /users查询支持的 HTTP 方法（CORS 预检）
常用状态码 12
200 OK请求成功
201 Created资源创建成功
204 No Content成功但无返回内容（如 DELETE）
301 Moved Permanently资源永久重定向
400 Bad Request请求参数错误或格式不合法
401 Unauthorized未认证（缺少或无效凭证）
403 Forbidden已认证但无权限访问
404 Not Found资源不存在
409 Conflict资源冲突（如重复创建）
422 Unprocessable Entity语义错误（字段校验失败）
429 Too Many Requests请求频率超限（触发限流）
500 Internal Server Error服务器内部错误
请求头 5
Content-Type: application/json请求体为 JSON 格式
Accept: application/json期望响应为 JSON
Authorization: Bearer <token>Bearer Token 认证头
If-None-Match: "etag"条件请求（ETag 缓存校验）
X-API-Key: abc123自定义 API Key 认证
响应格式 5
{ "data": [...], "meta": {...} }标准列表响应结构
{ "data": {...} }单资源响应结构
{ "error": { "code": "...", "message": "..." } }错误响应结构
{ "page": 2, "limit": 20, "total": 100 }分页元信息
Link: <url>; rel="next"分页链接头（RFC 5988）
认证方式 5
Authorization: Basic base64(user:pass)HTTP 基本认证
Authorization: Bearer <jwt>Bearer Token / JWT 认证
X-API-Key: <key>API Key 认证（自定义头）
?api_key=<key>API Key 认证（查询参数）
OAuth 2.0授权码模式（authorization code flow）
最佳实践 5
幂等性设计GET/PUT/DELETE 应幂等，多次调用结果一致
POST 创建返回 201 + Location创建成功返回 201 和资源 URI
批量操作: POST /users/batch批量创建/更新使用子资源端点
RateLimit-Limit / Retry-After限流响应头告知客户端配额
HATEOAS响应中包含相关资源链接（超媒体驱动）
💡 Tips
- URL 使用名词复数表示资源集合，如 /users 而不是 /user。
- GET 请求应该是安全的，不改变服务器状态；PUT/DELETE 应是幂等的。
- PUT 是完整替换，PATCH 是部分更新，根据场景选择。
- API 版本放在 URL 路径中（/v1/）或请求头中（Accept-Version）。
- 错误响应应包含错误码、消息和可选的详情字段，方便客户端处理。