Top REST API Design Pitfalls by Victor Rentea

Avoid exposing domain models directly in APIs - use DTOs and separate read/write models with CQRS pattern

Break down large endpoints into smaller, focused resources that reflect user intent rather than CRUD operations

Use proper HTTP status codes:

• 400 for client errors with helpful messages
• 422 for validation issues
• Avoid generic 500s without details

Consider versioning strategy carefully:

• Support multiple parallel versions when needed
• Use semantic versioning
• Plan for backwards compatibility
• Guard transitions with fitness functions

Implement proper error handling:

• Return descriptive error messages
• Include all validation errors, not just the first
• Localize error messages for clients

Design for evolution:

• Document decisions with ADRs (Architectural Decision Records)
• Use contract testing between services
• Monitor API usage patterns
• Plan for breaking changes

Optimize for common use cases:

• Implement bulk operations for lists
• Project only needed fields
• Consider read vs write performance separately

Protect sensitive data:

• Don’t leak internal IDs or structures
• Be careful with GDPR data
• Consider public vs private API needs

Think about client experience:

• Sit with users to understand needs
• Design around actual use cases
• Make APIs intuitive and semantic

Use proper tooling:

• Implement contract testing
• Set up distributed tracing
• Monitor API usage and performance