Back to Details

api-design-expert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Design Expert Skill

API设计专家技能

Expert in RESTful API design, OpenAPI/Swagger documentation, versioning strategies, error handling, and API best practices for NestJS applications.
精通NestJS应用中的RESTful API设计、OpenAPI/Swagger文档编写、版本控制策略、错误处理及API最佳实践。

When to Use

使用场景

  • Designing new API endpoints
  • Creating RESTful APIs
  • Writing OpenAPI/Swagger documentation
  • Implementing API versioning
  • Designing error responses
  • Creating DTOs and validation
  • Implementing pagination, filtering, sorting
  • 设计新的API端点
  • 创建RESTful API
  • 编写OpenAPI/Swagger文档
  • 实现API版本控制
  • 设计错误响应
  • 创建DTO及验证逻辑
  • 实现分页、过滤、排序功能

Project Context Discovery

项目上下文调研

Before providing guidance:
  1. Check 
    .agents/SYSTEM/ARCHITECTURE.md
    for API patterns
  2. Review existing controllers and DTOs
  3. Check for OpenAPI/Swagger setup
  4. Review versioning strategy
在提供指导前：
  1. 查看
    .agents/SYSTEM/ARCHITECTURE.md
    文件了解API模式
  2. 审阅现有控制器和DTO
  3. 检查OpenAPI/Swagger配置情况
  4. 审阅版本控制策略

Core Principles

核心原则

RESTful Design

RESTful设计

typescript
// Use nouns, plural, hierarchical
GET    /api/users
GET    /api/users/:id
POST   /api/users
PUT    /api/users/:id
DELETE /api/users/:id
GET    /api/users/:id/posts
typescript
// 使用名词、复数形式、层级结构
GET    /api/users
GET    /api/users/:id
POST   /api/users
PUT    /api/users/:id
DELETE /api/users/:id
GET    /api/users/:id/posts

HTTP Status Codes

HTTP状态码

  • 200 OK
    / 
    201 Created
    / 
    204 No Content
  • 400 Bad Request
    / 
    401 Unauthorized
    / 
    403 Forbidden
  • 404 Not Found
    / 
    409 Conflict
    / 
    500 Internal Server Error
  • 200 OK
    / 
    201 Created
    / 
    204 No Content
  • 400 Bad Request
    / 
    401 Unauthorized
    / 
    403 Forbidden
  • 404 Not Found
    / 
    409 Conflict
    / 
    500 Internal Server Error

Response Format

响应格式

typescript
// Single resource
{ "data": {...}, "meta": {...} }

// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }
typescript
// 单个资源
{ "data": {...}, "meta": {...} }

// 带分页的列表
{ "data": [...], "pagination": { "page", "limit", "total" } }

Error Format

错误格式

typescript
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [...],
    "timestamp": "...",
    "path": "/api/users"
  }
}
typescript
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [...],
    "timestamp": "...",
    "path": "/api/users"
  }
}

Best Practices

最佳实践

  • Consistent naming conventions
  • Validate all inputs with DTOs
  • OpenAPI/Swagger documentation
  • Authentication on all endpoints
  • Pagination for lists
  • Version APIs from the start
For complete DTO examples, pagination/filtering/sorting patterns, versioning strategies, OpenAPI setup, CRUD controller patterns, nested resources, bulk operations, and anti-patterns, see: 
references/full-guide.md
  • 统一命名规范
  • 使用DTO验证所有输入
  • 编写OpenAPI/Swagger文档
  • 所有端点添加认证机制
  • 列表数据实现分页
  • 从项目初期就进行API版本控制
如需完整的DTO示例、分页/过滤/排序模式、版本控制策略、OpenAPI配置、CRUD控制器模式、嵌套资源、批量操作及反模式相关内容，请参阅： 
references/full-guide.md