HTTP and REST Fundamentals: Request, Response, and DesignLesson 2.4

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.

DiagramCommon REST API Anti-Patterns

IMAGE PROMPT (replace this block with your generated image):

Flat warning-card grid infographic on white background. Title: 5 Common REST API Anti-Patterns. Five cards in a 3-2 grid layout. Each card has a red warning icon (triangle with !) in top left, a title in bold, and a 2-line description. Card 1: Title False 200 — returning HTTP 200 with error body. Shows a small code snippet: HTTP 200 OK / {status: error}. Card 2: Title Verbs in URLs — /getUser, /deleteOrder. Shows bad vs good example. Card 3: Title Chatty API — 5 requests for 1 page load. Shows five small request arrows vs one. Card 4: Title God Endpoint — POST /api?action=createUser. Card 5: Title No Versioning — breaking changes without a new version. Each card has a light red background (#fef2f2) with a #ef4444 top border. The fix for each anti-pattern shown in a small #3A5EFF text below. White card borders, rounded corners, white outer background.

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.