shipshitdev/api-design-expert

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

Before providing guidance:

1. Check .agents/memory/ for API patterns and architecture notes
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

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