itsual API and Interface Design
Overview
Good interfaces are hard to change later. Invest in clarity, consistency, and evolvability up front.
When to Use
- Designing new endpoints or services
- Changing existing public contracts
- Defining module or library boundaries
- Reviewing API proposals
Core Principles
- Clarity over cleverness
- Consistent naming and structure
- Explicit error models
- Backward compatibility as the default
- Documentation lives with the contract
Process
- Identify consumers and their needs
- Define resources/operations and their semantics
- Design request/response shapes and error cases
- Consider versioning and evolution strategy
- Document with examples
- Review for consistency with existing APIs
Checklist
- Resource naming is consistent and intuitive
- HTTP methods (or equivalent) used correctly
- Pagination, filtering, sorting considered where relevant
- Error responses are structured and actionable
- Authentication/authorization model is clear
- Breaking changes are avoided or explicitly versioned
- Examples are provided
Verification
- Contract is reviewable without reading implementation
- Common consumer scenarios are expressible cleanly
- Evolution path exists for likely future needs