API Design

Design consistent, well-documented APIs across REST, GraphQL, gRPC, and CLI interfaces.

When to Use

• Designing new API endpoints or commands
• Reviewing existing API contracts for consistency
• Establishing API naming and versioning conventions
• Planning backward-compatible API changes
• Generating API documentation or OpenAPI specs

Principles

1. Consistency - Same patterns everywhere (naming, error format, pagination)
2. Discoverability - A developer should guess the right endpoint/flag without reading docs
3. Backward compatibility - Additions are safe; removals and renames require versioning
4. Minimal surface - Expose only what consumers need; internal details stay internal
5. Self-describing errors - Error responses should tell the caller what went wrong and how to fix it