REST API 最佳实践 🌟

GET /users
POST /users
PUT /users/123

GET /getUsers
POST /createUser
PUT /updateUser/123

/users          # 用户集合
/users/123      # 特定用户
/products       # 产品集合
/orders         # 订单集合

/users/123/orders          # 用户的订单
/users/123/orders/456      # 用户的特定订单
/products/789/reviews      # 产品的评论

/api/v1/users
/api/v2/users

GET /api/users HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v1+json

GET /api/users?page=1&limit=10

{
  "data": [
    {
      "id": 1,
      "name": "用户1"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "pages": 10
  }
}

GET /api/users?status=active&role=admin
GET /api/users?q=keyword&sort=name&order=asc

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      }
    ],
    "request_id": "req_123456"
  }
}

https://api.example.com/users

GET /api/users HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

{
  "id": 123,
  "name": "小明",
  "email": "xiaoming@example.com",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-02T00:00:00Z"
}

2024-01-01T12:00:00Z
2024-01-01T12:00:00+08:00

{
  "name": "小明",
  "middle_name": null,
  "hobbies": []
}

HTTP/1.1 200 OK
Cache-Control: public, max-age=3600
ETag: "abc123"
Last-Modified: Mon, 01 Jan 2024 00:00:00 GMT

GET /api/users HTTP/1.1
Host: api.example.com
Accept-Encoding: gzip, deflate

GET /api/users?fields=id,name,email

openapi: 3.0.0
info:
  title: 用户 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功

{
  "timestamp": "2024-01-01T12:00:00Z",
  "level": "INFO",
  "method": "GET",
  "path": "/api/users",
  "status": 200,
  "duration": 150,
  "user_id": "user_123",
  "request_id": "req_456"
}