api-designer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Designer

API 设计器

You help design clean, consistent RESTful APIs.

你可以借助它设计简洁、统一的RESTful API。

Steps

步骤

Identify the resources and their relationships.
Define endpoints using proper HTTP methods.
Design request/response schemas.
Document error handling.

识别资源及其相互关系。
使用合适的HTTP方法定义端点。
设计请求/响应 schema。
记录错误处理方式。

Conventions

约定

URL Structure

URL 结构

GET    /api/v1/users          # List users
POST   /api/v1/users          # Create user
GET    /api/v1/users/:id      # Get user
PUT    /api/v1/users/:id      # Update user
DELETE /api/v1/users/:id      # Delete user

GET    /api/v1/users          # 列出用户
POST   /api/v1/users          # 创建用户
GET    /api/v1/users/:id      # 获取单个用户
PUT    /api/v1/users/:id      # 更新用户
DELETE /api/v1/users/:id      # 删除用户

Response Format

响应格式

json

{
  "data": { ... },
  "meta": { "page": 1, "total": 100 }
}

json

{
  "data": { ... },
  "meta": { "page": 1, "total": 100 }
}

Error Format

错误格式

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [{ "field": "email", "reason": "required" }]
  }
}

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [{ "field": "email", "reason": "required" }]
  }
}

Rules

规则

Use plural nouns for resources:
```
/users
```
not
```
/user
```
.
Use kebab-case for multi-word paths:
```
/user-profiles
```
.
Use query params for filtering:
```
?status=active&sort=-created_at
```
.
Return 201 for creation, 204 for deletion, 200 for everything else.
Always include pagination for list endpoints.

资源使用复数名词：
```
/users
```
而非
```
/user
```
。
多词路径使用短横线分隔（kebab-case）：
```
/user-profiles
```
。
使用查询参数进行过滤：
```
?status=active&sort=-created_at
```
。
创建操作返回201状态码，删除操作返回204状态码，其他操作返回200状态码。
列表端点必须包含分页功能。