REST API Design Anti-Patterns and How to Avoid Them
API anti-patterns, chatty API, over-fetching, under-fetching, false 200, breaking changes, God endpoint, versioning, documentation
REST API Design Anti-Patterns and How to Avoid Them
Learning REST API design means learning not only what to do but what to avoid. Anti-patterns are common mistakes that make APIs hard to use, brittle, and slow. Recognizing them early saves enormous maintenance effort later.
The False 200 Anti-Pattern
The most damaging REST API anti-pattern is returning 200 OK with an error body. Some developers return responses like {"status": "error", "message": "User not found"} with a 200 status code. This forces clients to parse the response body to determine success or failure, breaking the entire purpose of status codes. Always use the correct HTTP status code for every outcome.
Chatty APIs
A chatty API requires clients to make many small requests to accomplish a single task. For example, fetching a user's profile, then their preferences, then their recent orders as three separate requests when they are always needed together. The solution is to design endpoints that return composite responses for common use cases, or to implement query parameters that allow clients to request included related resources.
Over-Fetching and Under-Fetching
Over-fetching returns more data than the client needs, wasting bandwidth. Under-fetching returns too little, forcing multiple round trips. Design your response schemas by thinking about what clients actually need. Provide field selection via query parameters for flexibility: GET /users/42?fields=id,name,email.
Breaking Changes
Removing a field, renaming a field, or changing a field's data type in a response is a breaking change that will break existing clients. REST APIs must be backward-compatible. Add new fields freely — never remove or rename them without versioning.
The God Endpoint
Some developers create a single endpoint that handles many different operations based on a parameter: POST /api?action=createUser. This defeats the entire purpose of REST, breaks HTTP method semantics, and makes the API impossible to document or cache properly. Every resource and operation should have its own endpoint.