API

/api

Design REST or GraphQL API endpoints with schemas and validation.

Usage

/api <action> [resource] [--type <type>] [--methods <methods>]

Arguments

• action: design, scaffold, document, validate
• resource: Resource name (e.g., users, orders)
• --type: API type (rest, graphql) (default: rest)
• --methods: HTTP methods to include (default: all CRUD)

Instructions

When this skill is invoked:

Agent Behavior

Autonomy:

• Complete API design/scaffold end-to-end
• Follow REST/GraphQL best practices
• Generate OpenAPI/GraphQL schema

Quality:

• Consistent naming conventions
• Proper HTTP status codes
• Comprehensive validation
• Security considerations

Actions

Design (/api design <resource>)

Create API specification without code:

1. Analyze resource requirements:

   • Identify fields and types
   • Determine relationships
   • Note business rules

2. Generate specification:

   • Endpoint definitions
   • Request/response schemas
   • Error responses
   • Authentication requirements

3. Output OpenAPI spec or design document

Scaffold (/api scaffold <resource>)

Generate code for API endpoints:

1. Read prd/00_technology.md for framework patterns
2. Create route handler
3. Create request/response models
4. Create service layer
5. Create basic tests

Document (/api document)

Generate API documentation:

1. Scan existing endpoints
2. Generate OpenAPI/Swagger spec
3. Create markdown documentation

Validate (/api validate)

Check API against best practices:

1. Check naming conventions
2. Verify HTTP methods used correctly
3. Check response codes
4. Validate schema consistency

REST Design Principles

URL Structure

GET    /resources          # List all
GET    /resources/:id      # Get one
POST   /resources          # Create
PATCH  /resources/:id      # Partial update
PUT    /resources/:id      # Full replace
DELETE /resources/:id      # Delete

# Nested resources
GET    /users/:id/orders   # User's orders
POST   /users/:id/orders   # Create order for user

# Actions (when CRUD doesn't fit)
POST   /orders/:id/cancel  # Cancel order
POST   /users/:id/verify   # Verify user

Naming Conventions

• Use plural nouns for resources: /users not /user
• Use kebab-case for multi-word: /order-items
• Use lowercase: /users not /Users
• Avoid verbs in URLs (use HTTP methods)

HTTP Status Codes

Response Format

// Success (single resource)
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": { ... }
  }
}

// Success (collection)
{
  "data": [ ... ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      { "field": "email", "message": "Must be valid email" }
    ]
  }
}

API Specification Template

openapi: 3.0.3
info:
  title: Resource API
  version: 1.0.0

paths:
  /resources:
    get:
      summary: List resources
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'

    post:
      summary: Create resource
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResource'
      responses:
        '201':
          description: Created
        '400':
          description: Validation error

  /resources/{id}:
    get:
      summary: Get resource
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
        '404':
          description: Not found

Security Considerations

• Authentication required on protected endpoints
• Authorization checks for resource access
• Input validation on all endpoints
• Rate limiting configured
• Sensitive data not exposed in responses
• Audit logging for mutations

Example Output

$ /api design orders --type rest

Designing REST API for: orders

Resource Analysis:
- Primary entity: Order
- Related: User (owner), Items (children), Payment
- Operations: CRUD + cancel, refund

API Specification:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Endpoints
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

GET    /orders              List orders (with filters)
GET    /orders/:id          Get order details
POST   /orders              Create new order
PATCH  /orders/:id          Update order
DELETE /orders/:id          Delete order (soft delete)

POST   /orders/:id/cancel   Cancel order
POST   /orders/:id/refund   Request refund

GET    /orders/:id/items    List order items
POST   /orders/:id/items    Add item to order

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 Schemas
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Order:
  id: string (uuid)
  user_id: string (uuid)
  status: enum [draft, pending, confirmed, shipped, delivered, cancelled]
  total: number (decimal)
  currency: string (ISO 4217)
  items: OrderItem[]
  created_at: datetime
  updated_at: datetime

CreateOrder:
  items: CreateOrderItem[] (required, min: 1)
  shipping_address_id: string (required)
  payment_method_id: string (required)

OrderItem:
  id: string
  product_id: string
  quantity: integer (min: 1)
  unit_price: number
  total: number

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔒 Security
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- All endpoints require authentication
- Users can only access their own orders
- Admin role can access all orders
- Cancel/refund have time-based restrictions

Generated: openapi/orders.yaml

Next steps:
1. Review specification
2. Run `/api scaffold orders` to generate code
3. Run `/api document` to generate docs