kbwen / api-design

<!-- This is a SCAFFOLD skill -->

API Design

When to Apply

• Classification: feature, architecture-change, hotfix (if touching API endpoints)
• Phase: /implement (design & build), /review (compliance check), /test (contract verification)
• Trigger: Task involves creating, modifying, or deprecating API endpoints

Conventions

Customize after /app-init: Replace these generic conventions with your project's ADR decisions.

Endpoint Naming

• Use nouns for resources, not verbs: GET /users not GET /getUsers
• Plural resource names: /users, /orders, /products
• Nested resources for relationships: /users/:id/orders
• Use kebab-case for multi-word paths: /order-items

HTTP Methods

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": {
      "field": "email",
      "constraint": "required"
    }
  }
}

Standard Error Codes

Pagination

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "has_next": true
  }
}

Versioning

• URL path versioning: /api/v1/users
• Breaking changes require new version
• Deprecation: add Sunset header with date, keep old version for N months

Input Validation

• Validate at the controller/route level BEFORE business logic
• Return ALL validation errors at once (batch), not one at a time
• Sanitize strings: trim whitespace, escape HTML where applicable
• Enforce max lengths on all string fields

Checklist

During /implement:

• [ ] Every endpoint has input validation
• [ ] Every endpoint returns consistent error format
• [ ] Every endpoint has proper auth check (or explicit public annotation)
• [ ] Pagination for list endpoints
• [ ] Rate limiting consideration (at least documented in spec)
• [ ] No sensitive data in URL parameters (use body or headers)
• [ ] Request/response examples in spec match implementation

During /review:

• [ ] No N+1 query patterns in list endpoints
• [ ] Proper HTTP status codes (not everything is 200)
• [ ] Idempotency for PUT/DELETE
• [ ] Error messages don't leak internal details (stack traces, SQL, paths)
• [ ] CORS configured per ADR policy

Heading-Scoped Read Note

For phase-entry loading, read only:

• When to Apply
• Checklist

Load Conventions, Anti-Patterns, and References on full read or cache miss only.

Anti-Patterns

• God endpoint: One endpoint that does everything based on query params. Split into specific endpoints.
• Verb in URL: POST /createUser → POST /users
• Inconsistent naming: Mixing /user and /products (singular vs plural)
• Swallowing errors: Catching exceptions and returning 200 with { success: false }
• Leaking internals: Returning DB column names directly as API fields without mapping
• Missing 404: Returning empty 200 instead of 404 when resource doesn't exist
• Unbounded lists: List endpoints without pagination or default limits

References

• Project ADR: docs/adr/ADR-00N-project-architecture.md § API Design
• Security guardrails: .agent/rules/security_guardrails.md (A01: Access Control, A03: Injection)
• Spec template: .agentcortex/templates/spec-app-feature.md § API Contract