Bad API design compounds. A poorly designed endpoint becomes technical debt that multiplies every time a new client integrates. Good API design is invisible—it just works.
Principle 1: Design for Change
Your API will outlive your current feature set. Design for evolution:
- Use versioning from day one (
/v1/users) - Add fields, never remove them (deprecate instead)
- Return consistent error structures
- Document deprecation timelines
Principle 2: Make the Common Case Fast
90% of requests will hit 10% of your endpoints. Optimize for that:
- Support pagination by default
- Allow field filtering (
?fields=id,name,email) - Enable batch operations where it makes sense
- Cache aggressively with proper headers
Principle 3: Errors Are Part of the API
Error responses should be as thoughtfully designed as success responses:
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Account balance too low for this transaction",
"details": {
"required": 5000,
"available": 2500
}
}
}Principle 4: Authentication Is Non-Negotiable
Even internal APIs need auth. We default to:
- API keys for service-to-service communication
- OAuth 2.0 for user-delegated access
- JWT tokens for stateless authentication
- Role-based access control (RBAC)
The Documentation Problem
Your API documentation is lying. It's out of date the moment you deploy. We solve this with:
- OpenAPI specs generated from code
- Interactive documentation (Swagger/Stoplight)
- Real example requests and responses
When REST Isn't Enough
REST is great until it isn't. We reach for GraphQL when:
- Mobile clients need to minimize data transfer
- Frontend teams are blocked waiting for new endpoints
- You're dealing with complex, nested data structures
But GraphQL isn't free—it adds complexity. The decision should be driven by your constraints, not the hype cycle.
