API Design Expert Skill

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

Project Context Discovery

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

Core Principles

RESTful Design

// 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

HTTP Status Codes

• 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

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

// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }

Error Format

{
  "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

references/full-guide.md