API Design Skill

When to use this skill

Use when designing new API endpoints, modifying existing APIs, defining request/response contracts, or implementing API error handling.

API Design Principles

1. Contract first

• Define the API contract (types/schemas) before implementing
• The contract is the source of truth — code implements the contract
• Breaking contract changes require versioning

2. Predictability over cleverness

• Follow established conventions consistently
• A developer should guess the endpoint URL correctly on the first try
• Consistent naming, consistent response shapes, consistent error formats