Designing Clean REST APIs: Common Anti-Patterns and How to Fix Them

Jaibalaji B — Mon, 09 Nov 2026 13:37:18 +0000

Introduction
APIs are the backbone of modern software architecture. Whether you're building a backend for a mobile app or exposing services for third-party developers, a clean and intuitive API makes integration a breeze.

Unfortunately, many APIs fall into common design traps that make them confusing, brittle, and hard to maintain. Let's look at four anti-patterns and how to fix them.

Anti-Pattern 1: Using Verbs in URIs
REST is all about resources, not actions. Your URLs should represent nouns (collections or individual resources), and your HTTP methods (GET, POST, PUT, DELETE) should handle the actions.

❌ Bad:

POST /getUsers

POST /updateUser/5

GET /deleteUser/5

✅ Good:

GET /users (Retrieves all users)

PUT /users/5 (Updates user 5)

DELETE /users/5 (Deletes user 5)

Anti-Pattern 2: Ignoring Proper HTTP Status Codes
Returning a 200 OK status code for every response—even when an error occurs—forces client applications to parse the body just to see if a request failed.

Standard Status Codes to Use:

200 OK: Standard success response for GET, PUT, or PATCH.

201 Created: Success response when a resource is successfully created via POST.

204 No Content: Success response for a DELETE request with no body to return.

400 Bad Request: Malformed syntax or validation failure on the client side.

401 Unauthorized: Missing or invalid authentication credentials.

403 Forbidden: Authenticated user doesn't have permission for the action.

404 Not Found: The requested resource does not exist.

500 Internal Server Error: Unhandled server-side crash.

Anti-Pattern 3: Inconsistent Error Payloads
When an error occurs, clients need a predictable structure to display messages or handle retries. Returning a raw string text in one endpoint and a nested JSON object in another frustrates frontend developers.

✅ Consistent Error Payload Example:

JSON
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The 'email' field is required and must be a valid email address.",
"status": 400
}
}
Anti-Pattern 4: Forgetting Pagination, Filtering, and Sorting
If an endpoint like GET /products returns 50,000 items in a single array response, your database and client memory will crash.

The Fix: Always implement query parameters for collection endpoints:

Pagination: /products?page=2&limit=20 or cursor-based pagination (/products?cursor=eyJpZCI6MTAwfQ==).

Filtering: /products?category=electronics&status=in-stock

Sorting: /products?sort=-price (descending price)

Conclusion
Clean REST API design is an act of empathy for the developers consuming your service. By relying on proper resource naming, correct HTTP status codes, consistent error payloads, and built-in pagination, you build APIs that are resilient and developer-friendly.

Dockerize Like a Pro: 5 Best Practices for Lean and Secure Container Images

Jaibalaji B — Mon, 09 Nov 2026 13:35:21 +0000

Introduction
Docker has revolutionized how we build, ship, and run applications. By packaging code and dependencies into containers, we eliminate the dreaded "it works on my machine" bug.

However, dropping a monolithic app into a default Dockerfile can result in bloated image sizes, slow CI/CD pipelines, and hidden security vulnerabilities. Let’s look at five best practices to write clean, production-ready Dockerfiles.

1. Embrace Multi-Stage Builds
When building compiled languages or modern frontend frameworks (like React, Next.js, or Go), you need heavy build tools (compilers, npm packages, node_modules) during compilation, but only the final static artifacts or binaries in production.

The Solution: Use multi-stage builds to separate your build environment from your runtime environment.

Dockerfile

Stage 1: Build the application

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

Stage 2: Run the application

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]
This keeps your final production image lean by leaving behind compilers and source code.

2. Choose the Right Base Image
Avoid using ubuntu or debian as base images unless you specifically need full operating system utilities.

Alpine Linux: Extremely lightweight (often under 5MB) and secure, making it a favorite for production containers.

Distroless Images (by Google): Contain only your application and its runtime dependencies. They don't even include a shell or package manager, drastically reducing your attack surface.

3. Order Your Instructions for Optimal Caching
Docker builds images layer by layer, caching each step. If a layer changes, every subsequent layer must be rebuilt.

Best Practice: Copy your package manifests (package.json, requirements.txt) before copying your source code. That way, if you change a line of code, Docker won't re-download and reinstall all your dependencies.

Dockerfile

Do this:

COPY package*.json ./
RUN npm ci
COPY . . # Source code changes frequently, keep it at the bottom
4. Avoid Running as Root
By default, Docker containers run commands as the root user inside the container. If an attacker manages to exploit a vulnerability in your app, they instantly gain root privileges inside that container.

Best Practice: Create a non-privileged user and switch to it before starting your app:

Dockerfile
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
**5. Use .dockerignore
**Just like .gitignore, a .dockerignore file prevents unwanted files (like node_modules, .git, local environment variables, and log files) from being sent to the Docker daemon during the docker build command. This speeds up build times and prevents secret leaks.

Conclusion
Writing efficient Dockerfiles takes minor adjustments, but the payoff is massive: smaller images, faster deployments, and a significantly tighter security posture.

DEV Community: Jaibalaji B

Designing Clean REST APIs: Common Anti-Patterns and How to Fix Them

Dockerize Like a Pro: 5 Best Practices for Lean and Secure Container Images

Stage 1: Build the application

Stage 2: Run the application

Do this: