Common API Design Mistakes (and How to Avoid Them)

Common API Design Mistakes

API design mistakes are expensive to fix once clients depend on the API. Here are common mistakes and how to avoid them.

Mistake 1: Verbs in Paths

/getUsers, /createUser. Fix: use nouns. /users, /users/:id. The HTTP method is the verb.

Mistake 2: Wrong Status Codes

Returning 200 with an error body. Fix: use the right status code. 400 for validation, 401 for not authenticated, 404 for not found, 500 for server error. Clients should branch on the code alone.

Mistake 3: No Versioning

You ship /users. Six months later you change the response shape. All clients break. Fix: version from day one. /api/v1/users. Bump on breaking changes.

Mistake 4: No Pagination

/users returns every user. Fix: paginate. Use skip and limit, or cursor-based. Always cap limit. Return total for offset pagination.

Mistake 5: Inconsistent Response Shapes

One endpoint returns { data: ... }, another returns the raw resource, another returns { result: ... }. Fix: pick one shape and stick to it across all endpoints.

Mistake 6: Exposing Internal IDs or Fields

You return passwordHash, internal version numbers, or database-specific fields. Fix: use a serializer (DTO) that picks only the safe fields.

Mistake 7: No Input Validation

You trust the request body. Missing fields crash the server. Fix: validate with zod or express-validator. Reject bad data at the boundary.

Mistake 8: GET With Side Effects

You use GET to delete or update. GETs can be retried by browsers and crawlers. Fix: use POST, PUT, PATCH, or DELETE for non-idempotent actions.

Mistake 9: No Error Format

Errors come back in different shapes per endpoint. Fix: standardize. { error: 'message', code: '...'} or { errors: [...] }. Clients can rely on the shape.

Mistake 10: Long Paths With Deep Nesting

/users/:userId/posts/:postId/comments/:commentId/replies/:replyId. Fix: limit nesting to one level. Use /comments/:id with a filter for deeper resources.

Mistake 11: No Rate Limiting

Your API is open to abuse. Fix: add express-rate-limit. Global limiter plus stricter limiters on auth routes.

Mistake 12: No Documentation

The API works but only the author knows how to call it. Fix: write docs with Swagger or Postman. Keep them in sync with the code.

The Takeaway

Common API design mistakes: verbs in paths, wrong status codes, no versioning, no pagination, inconsistent response shapes, exposing internals, no validation, GET with side effects, no error format, deep nesting, no rate limiting, and no documentation. Avoid these from day one.