7 API Design Mistakes That Make Your Users Hate You (and How to Fix Them)

Every developer has used a terrible API. Inconsistent naming, cryptic errors, pagination that makes no sense. After reviewing 50+ production APIs (Stripe, GitHub, Twitch, and plenty of bad ones), I compiled the 7 most common design mistakes — and the exact patterns to fix them. 1. RPC-Style URLs Instead of Resources ❌ Bad: POST /getUsers POST /createUser POST /deleteUser ✅ Good: GET /users → List POST /users → Create GET /users/123 → Read PATCH /users/123 → Update DELETE /users/123 → Delete HTTP methods are your verbs. URLs should be nouns . This is REST 101, but 40% of APIs I reviewed still get it wrong. Exception: Actions that don not map to CRUD use a verb sub-resource: POST /articles/42/publish POST /payments/abc/refund 2. Mixing Naming Conventions { "firstName" : "John" , "last_name" : "Doe" , "Email-Address" : "john@example.com" } Pick ONE convention: { "first_name" : "John" , "last_name" : "Doe" , "email_address" : "john@example.com" } Where Convention Example URL paths kebab-ca