API Design Mistakes That Will Haunt You (I've Made All of Them)

I've built 50+ APIs. Here are the mistakes I keep seeing — including ones I made myself. 1. Inconsistent Naming # BAD — mixing styles GET /getUsers GET /user_list GET /fetch-all-products POST /CreateOrder # GOOD — consistent kebab-case, resource-based GET /users GET /products POST /orders GET /users/{id}/orders Pick ONE naming convention and stick to it across every endpoint. 2. Not Using Proper HTTP Methods # BAD POST /deleteUser?id=123 GET /createOrder POST /getUsers # GOOD DELETE /users/123 POST /orders GET /users 3. Returning Inconsistent Error Formats // BAD — different error format every time { "error" : "Not found" } { "message" : "Unauthorized" , "code" : 401 } { "err" : true , "msg" : "Bad input" } // GOOD — consistent error envelope { "error" : { "code" : "NOT_FOUND" , "message" : "User with ID 123 not found" , "details" : {} } } 4. Not Versioning from Day 1 # BAD — no version, breaking changes break all clients GET /users # GOOD — versioned from the start GET /v1/users # OR