RESTful API Cheatsheet - REST API Design Reference
Inconsistent endpoint naming is what turns a healthy API into a guessing game for every frontend engineer. Organized by URL design, methods, status codes, headers/formats, auth and practices, each entry is a convention you can apply directly. Use it to sketch a resource model, choose /users/{id} over /getUser, and align on error framing. After reading you produce an API whose shape your frontend bets on safely.
URL Design Spec 6
/api/v1/users资源set（复数名词）
/api/v1/users/123单个资源（ID 定位）
/api/v1/users/123/orders子资源嵌套
/api/v1/users?role=admin查询OptionsFilter
/api/v1/users?page=2&limit=20分页Options
/api/v1/users?sort=-created_atsort（- 表示descending）
HTTP Methods 8
GET /usersGet资源list（安全、幂）
GET /users/123Get单个资源
POST /usersCreate资源（非幂）
PUT /users/123完整Update资源（幂）
PATCH /users/123部分Update资源
DELETE /users/123Delete资源（幂）
HEAD /users/123只Getresponse头，不返回 body
OPTIONS /users查询supports的 HTTP method（CORS 预检）
Common Status Codes 12
200 OKrequest成功
201 Created资源Create成功
204 No Content成功但无返回内容（如 DELETE）
301 Moved Permanently资源永久redirect
400 Bad RequestrequestOptions错误or格式不合法
401 Unauthorized未认证（缺少or无效凭证）
403 Forbidden已认证但无Permission访问
404 Not Found资源不exists
409 Conflict资源冲突（如重复Create）
422 Unprocessable Entity语义错误（field校验失败）
429 Too Many Requestsrequest频率超限（触发限流）
500 Internal Server ErrorService器内部错误
Request Headers 5
Content-Type: application/jsonrequest体为 JSON 格式
Accept: application/json期望response为 JSON
Authorization: Bearer <token>Bearer Token 认证头
If-None-Match: "etag"conditionrequest（ETag cache校验）
X-API-Key: abc123自定义 API Key 认证
Response Format 5
{ "data": [...], "meta": {...} }标准listresponse结构
{ "data": {...} }单资源response结构
{ "error": { "code": "...", "message": "..." } }错误response结构
{ "page": 2, "limit": 20, "total": 100 }分页元信息
Link: <url>; rel="next"分页链接头（RFC 5988）
Auth Methods 5
Authorization: Basic base64(user:pass)HTTP 基本认证
Authorization: Bearer <jwt>Bearer Token / JWT 认证
X-API-Key: <key>API Key 认证（自定义头）
?api_key=<key>API Key 认证（查询Options）
OAuth 2.0授权码模式（authorization code flow）
Best Practices 5
幂等性设计GET/PUT/DELETE 应幂，多次call结果一致
POST 创建返回 201 + LocationCreate成功返回 201 和资源 URI
批量操作: POST /users/batchbatchCreate/Update使用子资源端点
RateLimit-Limit / Retry-After限流response头告知客户端配额
HATEOASresponse中package含相关资源链接（超媒体驱动）
Tips
- Use plural nouns for resource collections in URLs, e.g. /users not /user.
- GET should be safe (no server state change); PUT/DELETE should be idempotent.
- PUT fully replaces; PATCH partially updates — choose by scenario.
- Put the API version in the URL path (/v1/) or a request header (Accept-Version).
- Error responses should include a code, message, and optional details for easy client handling.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Jul 21, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us