Layered architecture: separating concerns from day one
The most common mistake in Node.js APIs is writing business logic directly inside route handlers. It works fine for the first few endpoints, then becomes a maintenance crisis as the codebase grows. The solution is a layered architecture where each layer has a single responsibility: the route layer handles HTTP parsing and response shaping, the controller layer orchestrates the request flow, the service layer contains business logic, and the data access layer handles all persistence operations.
This separation is not about following a pattern for its own sake — it produces concrete, measurable benefits. Services become unit-testable without spinning up an HTTP server. Business logic can be reused across REST endpoints, GraphQL resolvers, and background jobs without duplication. The data access layer can be swapped from raw SQL to an ORM without touching a single line of business logic. When a requirement changes — and it always does — you change it in one place.
In practice, the folder structure looks like this: `src/routes/` contains Express router files grouped by domain (auth, users, projects), `src/controllers/` contains thin request handlers that call services and format responses, `src/services/` contains all business logic and is where the real work happens, `src/repositories/` or `src/db/` contains all database queries, and `src/middleware/` contains auth guards, rate limiters, and request loggers.
TypeScript makes this architecture significantly more powerful. Define interface types for each layer boundary — the shape of a service method's return value, the expected structure of a repository's query result — and the compiler will catch mismatches immediately. A service that returns a UserDTO never leaks a raw database row to the controller, because the return type prevents it.
- Keep route handlers under 15 lines — if they're longer, extract the logic into a controller or service.
- Never import database models or query builders directly inside route files.
- Define a typed DTO (Data Transfer Object) for every service method's return value.
- Use dependency injection or a simple module pattern to make services testable without mocking HTTP.
- Group files by domain (users, orders, products) rather than by type (all controllers in one folder).
Middleware patterns that handle cross-cutting concerns
Middleware is the right place for anything that applies to many routes: authentication, authorization, rate limiting, request logging, input sanitization, and CORS configuration. The key is to treat each piece of middleware as a standalone, composable unit that can be applied selectively — not a monolithic function that checks a dozen conditions in one place.
Authentication middleware should validate the JWT or session token, attach the decoded user object to the request (via TypeScript declaration merging on Express's Request type), and call next(). If the token is invalid, it should respond with a 401 immediately without calling the route handler. Authorization middleware — whether the authenticated user has permission to perform this specific action — is separate from authentication and runs after it.
Rate limiting with express-rate-limit protects your API from abuse and accidental DDoS. Configure it per-route rather than globally: an auth endpoint (login, signup) warrants a strict limit (5 requests per 15 minutes per IP), while a public data endpoint can be more generous (100 requests per minute). Store rate limit state in Redis rather than in-memory when running multiple Node.js instances — in-memory limits are per-instance and effectively useless in a load-balanced deployment.
Request logging middleware using Morgan or Pino gives you structured logs that include method, path, status code, response time, and request ID. The request ID — a UUID generated at the start of each request and attached to all log entries — is what makes debugging distributed systems tractable. Pass it back to the client in the response headers so frontend engineers can correlate client errors with server logs.
- Use TypeScript declaration merging to type `req.user` instead of casting to `any` in every handler.
- Apply rate limiting per endpoint based on sensitivity — not a single global limit.
- Store rate limit state in Redis for any multi-instance deployment.
- Generate a unique request ID with `crypto.randomUUID()` in middleware and attach it to all log entries.
- Test auth middleware in isolation with unit tests — do not rely solely on integration tests.
Validation and error handling as first-class features
The quality of an API's error handling is directly proportional to how fast frontend teams can build against it. Vague 500 errors with no details force developers to add console.log statements and guess at what broke. Consistent, structured error responses with meaningful messages and machine-readable error codes let frontend teams handle errors gracefully without constant backend consultation.
Use Zod or Joi for request validation at the controller boundary. Zod is my preference in TypeScript projects because its inferred types eliminate the need to write separate TypeScript interfaces for your API payloads — the schema IS the type. Wrap each route's input validation in a reusable middleware factory that accepts a Zod schema, validates req.body (or req.query, or req.params), and returns a 400 with a structured validation error array if validation fails.
Define a standard error response shape across the entire API and stick to it absolutely. Every error response should have: a status field (error), an HTTP status code, a message field for human consumption, a code field for machine consumption (e.g., 'VALIDATION_ERROR', 'RESOURCE_NOT_FOUND', 'UNAUTHORIZED'), and optionally a details field for field-level validation errors. Register a global Express error handler as the last middleware to catch any unhandled errors and shape them to this format.
Distinguish between operational errors (expected failures: user not found, validation failed, insufficient permissions) and programmer errors (unexpected failures: uncaught exceptions, database connection lost). Operational errors should be handled gracefully and return appropriate HTTP status codes. Programmer errors should be logged with full stack traces, alerted to your monitoring system (Sentry, Datadog), and not expose internal details in the response body.
- Use Zod schemas as both runtime validators and TypeScript type sources — `z.infer<typeof schema>`.
- Create a reusable `validateRequest(schema)` middleware factory that validates body, query, and params.
- Define a global Express error handler as the final `app.use()` call to catch all unhandled errors.
- Use HTTP status codes semantically: 400 for bad input, 401 for unauthenticated, 403 for unauthorized, 404 for not found, 422 for business rule violations, 500 for server errors.
- Log programmer errors with full stack traces to Sentry or similar — never swallow them silently.
Caching strategies that actually scale
Caching is one of the most impactful and most misunderstood performance techniques in backend development. Applied correctly, it can reduce database load by 90% and drop API response times from 200ms to under 5ms for frequently requested data. Applied incorrectly, it serves stale data to users and creates bugs that are nightmarish to debug in production.
The caching hierarchy for a Node.js API typically has three layers: in-process cache (fast but not shared between instances), distributed cache (Redis — shared across instances, survives restarts), and CDN edge cache (fastest, but only for public, non-personalized responses). Choose the right layer based on the data's update frequency, the cost of serving stale data, and whether the response is user-specific.
Redis is the standard for distributed API caching. Cache the results of expensive database queries by constructing a cache key from the query parameters. On write operations, invalidate or update the affected cache entries immediately rather than waiting for TTL expiration. Use cache-aside (read-through) for most cases: check the cache first, fetch from DB on miss, populate the cache, return the result. Use write-through for data that must never be stale for more than a few seconds.
HTTP cache headers are a free performance layer that most APIs underutilize. For public, non-personalized responses (a list of articles, a product catalog), set Cache-Control: public, max-age=3600. For private, user-specific responses, set Cache-Control: private, no-store. Adding ETag headers enables conditional requests — the client sends the ETag with its next request, and if the data hasn't changed, the server responds with 304 Not Modified and no body, saving bandwidth.
- Cache at the service layer, not the repository layer — you want to cache business results, not raw DB rows.
- Construct Redis cache keys deterministically: `${resourceType}:${id}` or `${listType}:${JSON.stringify(filters)}`.
- Set TTLs appropriate to data volatility — user sessions 24h, product data 1h, real-time data 30s.
- Invalidate cache entries on write operations using the same key construction logic.
- Add Cache-Control headers to all HTTP responses, including error responses.
Designing for maintainability and team growth
An API designed for a solo developer will start showing cracks the moment a second developer joins the project. The patterns that enable team scale are not exotic — they're disciplined application of the same principles that make any software maintainable: clear naming, single responsibility, documented contracts, and automated safety nets.
API versioning is one of the most important decisions to make before launch, because changing it later is painful. The standard approach for REST APIs is URL versioning: /api/v1/users. This allows you to introduce breaking changes in /api/v2 while maintaining v1 for existing clients. Never break existing endpoints without a versioned migration path — this is a trust violation with your API consumers.
Automated testing at multiple layers is non-negotiable for APIs that teams depend on. Unit tests cover service logic in isolation using mocked repositories. Integration tests cover the full request-response cycle including the database using a test database seeded with known data. Contract tests (using tools like Pact) verify that the API's actual response shapes match the documented schema. Run all tests in CI on every pull request.
OpenAPI (Swagger) documentation generated from your actual route definitions (using tools like tsoa or express-openapi-validator) creates a single source of truth for your API. When the documentation is generated from code, it cannot drift out of date — which means frontend teams, QA engineers, and third-party integrators can trust it. Auto-generated Postman collections from your OpenAPI spec remove the manual overhead of keeping request examples up to date.
- Version your API from day one with /api/v1 — retrofitting versioning is expensive.
- Write unit tests for every service method before the service is used in a route.
- Use a test database with seed data for integration tests — never run tests against a shared development database.
- Generate OpenAPI documentation from code using tsoa or zod-to-openapi rather than writing it manually.
- Set up automated dependency updates with Renovate Bot or Dependabot to keep security patches current.
Share this article
Help others discover this resource and extend the reach of the content.
