After reviewing hundreds of APIs, here are the 12 most common design flaws I see (and how to fix them):
1. Using verbs instead of resource names. Your endpoints should represent resources, not actions. Keep URLs simple and predictable. ❌ /getUser → ✅ /users/{id}
2. Ignoring HTTP method semantics. When everything is POST, nothing makes sense. Use GET, POST, PUT, PATCH, and DELETE appropriately—they exist for a reason.
3. Forgetting idempotency for critical operations. A duplicate payment request shouldn't charge users twice. Implement idempotency keys or database constraints for operations like payments and orders.
4. Deploying without versioning: Maintain backward compatibility from day one. Version your APIs through URL paths (/v1/users) or Accept headers.
5. Returning vague error responses. Status codes are part of your API contract. Make errors actionable, consistent, and safe to expose publicly.
6. Skipping pagination at scale
- Offset pagination for simple use cases
- Cursor-based pagination for real-time and large datasets
7. Neglecting filtering and sorting capabilities. Implement query parameters with proper database indexing to keep queries performant as you scale.
8. Treating security as an afterthought: Use OAuth 2.0, JWT, or API keys from the start. Always validate and refresh tokens properly.
9. Launching without rate limiting. Protect your infrastructure before someone abuses it. Return proper headers (X-RateLimit-Remaining) and status codes (429) when limits are exceeded.
10. Misconfiguring cache strategies. Leverage HTTP caching headers (ETag, Cache-Control) to cache frequent responses, reducing latency and costs.
11. Shipping undocumented APIs: Use OpenAPI/Swagger to document every endpoint with clear examples. Your future self (and teammates) will thank you.
12. Treating REST as dogma: REST is a guideline, not a religion. Prioritize consistency and clarity over architectural purity.
Fix these 12 issues, and your APIs will be easier to use, scale, and maintain.