designing-apis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Designing APIs

API设计

Workflows

工作流程

REST Principles

REST设计原则

Resource Naming

资源命名

Use nouns, not verbs:
```
/users
```
not
```
/getUsers
```
Use plural:
```
/users
```
not
```
/user
```
Use kebab-case:
```
/user-profiles
```
not
```
/userProfiles
```
Nest for relationships:
```
/users/{id}/orders
```

使用名词而非动词：
```
/users
```
而非
```
/getUsers
```
使用复数形式：
```
/users
```
而非
```
/user
```
使用短横线分隔（kebab-case）：
```
/user-profiles
```
而非
```
/userProfiles
```
通过嵌套表示关系：
```
/users/{id}/orders
```

HTTP Methods

HTTP请求方法

Method	Purpose	Idempotent
GET	Read	Yes
POST	Create	No
PUT	Replace	Yes
PATCH	Update	Yes
DELETE	Remove	Yes

方法	用途	幂等性
GET	读取	是
POST	创建	否
PUT	替换	是
PATCH	更新	是
DELETE	删除	是

Status Codes

状态码

Code	Meaning
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
500	Internal Server Error

状态码	含义
200	请求成功
201	创建成功
204	无内容
400	错误请求
401	未授权
403	禁止访问
404	资源不存在
409	冲突
422	无法处理的实体
500	服务器内部错误

Error Response Format

错误响应格式

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Versioning

版本控制

URL Versioning (Recommended)

URL版本控制（推荐）

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

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

Header Versioning

请求头版本控制

GET /api/users
Accept: application/vnd.api+json;version=1

GET /api/users
Accept: application/vnd.api+json;version=1

Pagination

分页

json

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

json

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

OpenAPI Example

OpenAPI示例

yaml

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

yaml

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'