api-designer

Purpose

The api-designer skill provides comprehensive guidance for designing robust, RESTful APIs and function contracts that serve as clear interfaces for feature implementations. This skill helps the Architecture Designer agent create well-structured, documented, and maintainable API designs that follow industry best practices.

This skill emphasizes:

• REST Principles: Proper resource design, HTTP method usage, and status codes
• Clear Contracts: Well-defined request/response schemas
• Error Handling: Consistent error response formats
• Authentication: Security patterns and authorization strategies
• Documentation: Comprehensive API documentation for consumers

The api-designer skill ensures that APIs are intuitive, consistent, and provide excellent developer experience for both internal and external consumers.

When to Use

This skill auto-activates when the agent describes:

• "Design API endpoints for..."
• "Create REST API for..."
• "Define function contract for..."
• "Specify request/response schemas..."
• "Design authentication for..."
• "Plan API structure with..."
• "Define error responses for..."
• "Create API documentation for..."

Provided Capabilities

1. REST API Endpoint Design

What it provides:

• Resource identification and naming
• HTTP method selection (GET, POST, PUT, PATCH, DELETE)
• URL structure and path parameters
• Query parameter design
• Status code selection
• Idempotency considerations

REST Principles:

• Resources as nouns, not verbs
• HTTP methods for actions
• Stateless design
• Standard status codes
• HATEOAS (optional)

Example:

from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime

# ==================== RESOURCE: Users ====================

class UserCreate(BaseModel):
    """Request schema for creating user."""
    username: str = Field(..., min_length=3, max_length=50)
    email: str = Field(...)
    full_name: str = Field(..., min_length=1, max_length=200)

class UserResponse(BaseModel):
    """Response schema for user."""
    id: int
    username: str
    email: str
    full_name: str
    is_active: bool
    created_at: datetime

class UserUpdate(BaseModel):
    """Request schema for updating user (all optional)."""
    email: Optional[str] = None
    full_name: Optional[str] = None
    is_active: Optional[bool] = None

class UserList(BaseModel):
    """Response schema for user list with pagination."""
    items: List[UserResponse]
    total: int
    page: int
    page_size: int
    total_pages: int

# API Endpoints
"""
POST   /api/v1/users              Create new user
GET    /api/v1/users              List users (with pagination)
GET    /api/v1/users/{user_id}    Get user by ID
PUT    /api/v1/users/{user_id}    Update user (full replace)
PATCH  /api/v1/users/{user_id}    Update user (partial)
DELETE /api/v1/users/{user_id}    Delete user

Query Parameters for GET /api/v1/users:
- page: int = 1          (pagination)
- page_size: int = 20    (items per page)
- search: str = None     (search filter)
- is_active: bool = None (status filter)
- sort_by: str = "created_at"
- sort_order: str = "desc"

Status Codes:
- 200 OK: Successful GET, PUT, PATCH
- 201 Created: Successful POST
- 204 No Content: Successful DELETE
- 400 Bad Request: Invalid input
- 401 Unauthorized: Authentication required
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource not found
- 409 Conflict: Resource conflict (duplicate)
- 422 Unprocessable Entity: Validation error
- 500 Internal Server Error: Server error
"""