Back to Details

rest-api-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

REST API Design

REST API设计

Design RESTful APIs with proper conventions and developer experience.
设计遵循规范的RESTful API，兼顾开发者体验。

Resource Naming

资源命名

undefined
undefined

Good - nouns, plural, hierarchical

推荐写法 - 名词、复数、层级结构

GET /api/users GET /api/users/123 GET /api/users/123/orders POST /api/users PATCH /api/users/123 DELETE /api/users/123
GET /api/users GET /api/users/123 GET /api/users/123/orders POST /api/users PATCH /api/users/123 DELETE /api/users/123

Bad - verbs, actions in URL

不推荐写法 - 动词、URL中包含动作

GET /api/getUsers POST /api/createUser POST /api/users/123/delete
undefined
GET /api/getUsers POST /api/createUser POST /api/users/123/delete
undefined

HTTP Methods

HTTP方法

MethodPurposeIdempotent
GETRead resourceYes
POSTCreate resourceNo
PUTReplace resourceYes
PATCHPartial updateYes
DELETERemove resourceYes
方法用途幂等性
GET读取资源是
POST创建资源否
PUT替换资源是
PATCH部分更新是
DELETE删除资源是

Status Codes

状态码

CodeMeaningUse For
200OKSuccessful GET, PATCH
201CreatedSuccessful POST
204No ContentSuccessful DELETE
400Bad RequestValidation errors
401UnauthorizedMissing auth
403ForbiddenInsufficient permissions
404Not FoundResource doesn't exist
429Too Many RequestsRate limited
状态码含义适用场景
200请求成功成功的GET、PATCH请求
201创建成功成功的POST请求
204无内容成功的DELETE请求
400错误请求验证失败
401未授权缺少认证信息
403禁止访问权限不足
404未找到资源不存在
429请求过多触发速率限制

Response Format

响应格式

json
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "john@example.com"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}
json
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "john@example.com"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Collection Response

集合响应

json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2"
  }
}
json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2"
  }
}

Query Parameters

查询参数

GET /api/products?category=electronics    # Filtering
GET /api/products?sort=-price,name        # Sorting
GET /api/products?page=2&limit=20         # Pagination
GET /api/products?fields=id,name,price    # Field selection
GET /api/products?category=electronics    # 过滤
GET /api/products?sort=-price,name        # 排序
GET /api/products?page=2&limit=20         # 分页
GET /api/products?fields=id,name,price    # 字段选择

Best Practices

最佳实践

  • Use nouns for resources, not verbs
  • Version API via URL path (
    /api/v1/
    )
  • Return appropriate status codes
  • Include pagination for collections
  • Document with OpenAPI/Swagger
  • 使用名词表示资源，而非动词
  • 通过URL路径为API添加版本标识（
    /api/v1/
    ）
  • 返回合适的状态码
  • 为集合类接口添加分页功能
  • 使用OpenAPI/Swagger进行文档编写