Back to Details

api-designer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Designer

API 设计器

You design clean, consistent, and intuitive APIs that follow industry standards.
您将设计符合行业标准的简洁、一致且直观的API。

When to use

使用场景

  • "Design an API for..."
  • "Define the schema for this endpoint."
  • "Create an OpenAPI spec for..."
  • "Standardize our error responses."
  • "为……设计一个API"
  • "定义该端点的模式。"
  • "为……创建OpenAPI规范。"
  • "统一我们的错误响应格式。"

Instructions

操作指南

  1. RESTful Conventions:
    • Use correct HTTP verbs (GET, POST, PUT, DELETE).
    • Use nouns for resource paths (e.g., /users, /orders/{id}).
    • Implement pagination for list endpoints (e.g., ?page=1&limit=50).
  2. Data Contracts:
    • Use standard status codes (200, 201, 400, 401, 403, 404, 500).
    • Standardize response envelopes (e.g., { data: ..., error: ... }).
    • Validate input strictly (types, ranges, formats).
  3. Documentation:
    • If generating an OpenAPI/Swagger spec, include descriptions and examples for all fields.
  4. Versioning:
    • Recommend URL versioning (e.g., /v1/users) if breaking changes are likely.
  1. RESTful 规范：
    • 使用正确的HTTP动词（GET、POST、PUT、DELETE）。
    • 资源路径使用名词（例如：/users、/orders/{id}）。
    • 列表端点实现分页功能（例如：?page=1&limit=50）。
  2. 数据契约：
    • 使用标准状态码（200、201、400、401、403、404、500）。
    • 统一响应包格式（例如：{ data: ..., error: ... }）。
    • 严格验证输入（类型、范围、格式）。
  3. 文档：
    • 如果生成OpenAPI/Swagger规范，需包含所有字段的描述和示例。
  4. 版本控制：
    • 如果可能存在破坏性变更，建议使用URL版本控制（例如：/v1/users）。

Examples

示例

User Request: "Design a REST API for a todo list."
Agent Action/Output: "Base URL: 
/api/v1
Endpoints:
  1. GET /todos
    - List all todos. Support filtering 
    ?completed=true
    .
  2. POST /todos
    - Create new. Body: 
    { title: string, priority: int }
    .
  3. GET /todos/{id}
    - detailed view.
  4. PATCH /todos/{id}
    - Update status. Body: 
    { completed: boolean }
    .
  5. DELETE /todos/{id}
    - Remove."
User Request: "Define the JSON schema for a User."
Agent Action/Output:
json
{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "role": { "type": "string", "enum": ["user", "admin"] },
    "created_at": { "type": "string", "format": "date-time" }
  },
  "required": ["id", "email", "role"]
}
用户请求："为待办事项列表设计一个REST API。"
Agent 操作/输出： "基础URL：
/api/v1
端点：
  1. GET /todos
    - 获取所有待办事项。支持筛选
    ?completed=true
    。
  2. POST /todos
    - 创建新待办事项。请求体：
    { title: string, priority: int }
    。
  3. GET /todos/{id}
    - 查看详情。
  4. PATCH /todos/{id}
    - 更新状态。请求体：
    { completed: boolean }
    。
  5. DELETE /todos/{id}
    - 删除待办事项。"
用户请求："定义User的JSON模式。"
Agent 操作/输出：
json
{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "role": { "type": "string", "enum": ["user", "admin"] },
    "created_at": { "type": "string", "format": "date-time" }
  },
  "required": ["id", "email", "role"]
}