URL Parameters vs Query Strings in Express.js

turn res.status(400).json({ error: Missing required path parameters: ${missing.join(', ')} }); } next(); }; }

function validateQueryTypes(schema: Record<string, 'string' | 'number' | 'boolean'>) { return (req: Request, res: Response, next: NextFunction) => { const errors: string[] = []; for (const [key, expectedType] of Object.entries(schema)) { if (req.query[key] !== undefined) { const value = req.query[key]; if (expectedType === 'number' && isNaN(Number(value))) { errors.push(${key} must be a valid number); } if (expectedType === 'boolean' && !['true', 'false'].includes(String(value).toLowerCase())) { errors.push(${key} must be true or false); } } } if (errors.length > 0) { return res.status(400).json({ error: 'Invalid query parameters', details: errors }); } next(); }; }

// Apply middleware router.get('/v1/inventory', validateQueryTypes({ page: 'number', limit: 'number', active: 'boolean' }), /* handler /); router.get('/v1/inventory/:sku', validatePathParams(['sku']), / handler */);

### Architecture Decisions & Rationale

1. **Strict Path Validation**: Path parameters are required by definition. Failing fast on malformed identifiers prevents downstream database queries and reduces attack surface.
2. **Query Coercion Layer**: Query strings are inherently unstructured. Centralizing type conversion and boundary enforcement (e.g., `limit` capped at 100) prevents resource exhaustion and inconsistent responses.
3. **Middleware Composition**: Validation logic is decoupled from business logic. This enables independent testing, easier OpenAPI generation, and consistent error formatting across the API surface.
4. **Response Shape Consistency**: Collection endpoints return paginated envelopes. Single-resource endpoints return raw entities. This aligns with client expectations and simplifies state management in frontend applications.

## Pitfall Guide

### 1. Treating Path Parameters as Optional
**Explanation**: Developers sometimes define routes like `/api/items/:id?` expecting Express to handle missing values gracefully. Express routing does not support optional path segments natively without regex workarounds, and doing so breaks REST semantics.
**Fix**: Split into two explicit routes: `/api/items` for collections and `/api/items/:id` for single resources. Use middleware to share business logic if needed.

### 2. Ignoring String Coercion in `req.params`
**Explanation**: All path parameters arrive as strings. Passing them directly to numeric database queries or mathematical operations causes silent type mismatches or query failures.
**Fix**: Always coerce immediately after extraction. Use `parseInt()` or `Number()` with explicit radix, and validate against expected ranges before downstream usage.

### 3. Overloading Query Strings for Resource Identification
**Explanation**: Using `/api/users?id=42` instead of `/api/users/42` breaks CDN caching, complicates bookmarking, and violates REST conventions. Proxies may strip or reorder query parameters, causing cache fragmentation.
**Fix**: Reserve query strings exclusively for filtering, sorting, pagination, and representation control. Move all resource identifiers into path segments.

### 4. Missing Sanitization on Query Inputs
**Explanation**: Query strings are user-controlled and often bypass input validation pipelines. Unsanitized values can trigger NoSQL injection, SQL injection, or excessive memory allocation during sorting/filtering.
**Fix**: Implement a strict allowlist for query keys. Sanitize string values, enforce numeric bounds, and reject unknown parameters with a `400 Bad Request` response.

### 5. Inconsistent Naming Conventions Across Endpoints
**Explanation**: Mixing `userId`, `user_id`, and `userUuid` across routes forces client SDKs to maintain mapping tables and increases documentation drift.
**Fix**: Adopt a single naming strategy (e.g., camelCase for all parameters) and enforce it via linting rules or OpenAPI schema validation. Document the convention in the API style guide.

### 6. Forgetting to Handle Undefined Query Values
**Explanation**: Accessing `req.query.sortBy` without checking for `undefined` causes runtime errors when the client omits the parameter. Defaulting logic scattered across handlers creates maintenance debt.
**Fix**: Centralize query extraction in a dedicated utility function. Apply defaults at the extraction layer, not inside route handlers.

### 7. Mixing Identification and Filtering in the Same Segment
**Explanation**: Routes like `/api/products/electronics/active` conflate category identification with status filtering. This creates exponential route combinations and prevents flexible client queries.
**Fix**: Use `/api/products?category=electronics&status=active`. Path segments should represent hierarchical resource ownership, not attribute filtering.

## Production Bundle

### Action Checklist
- [ ] Audit existing routes: Separate resource identifiers from filters, ensuring path segments contain only mandatory IDs
- [ ] Implement strict path validation: Reject malformed identifiers before database interaction
- [ ] Centralize query extraction: Create a typed utility for coercion, defaults, and boundary enforcement
- [ ] Add unknown parameter rejection: Return `400` when clients send unregistered query keys
- [ ] Configure CDN cache keys: Exclude non-essential query parameters from cache invalidation rules
- [ ] Document semantic contracts: Specify which parameters are path-bound vs query-bound in OpenAPI specs
- [ ] Add integration tests: Verify routing behavior with missing, malformed, and edge-case inputs
- [ ] Monitor routing performance: Track cache hit ratios and query complexity to identify optimization opportunities

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Fetching a single entity by ID | Path Segment (`/v1/orders/:orderId`) | Enables aggressive CDN caching, aligns with REST, simplifies client routing | Low (standard implementation) |
| Filtering a collection by attributes | Query Modifier (`/v1/orders?status=pending&date=2024-01`) | Keeps route table flat, supports dynamic combinations, prevents exponential path growth | Medium (requires validation layer) |
| Nested resource ownership | Path Segment (`/v1/users/:userId/posts/:postId`) | Represents hierarchical relationship, maintains resource identity | Low |
| Pagination and sorting | Query Modifier (`/v1/posts?page=2&sort=created`) | Optional by nature, varies per request, does not change resource identity | Low |
| Feature toggles or representation control | Query Modifier (`/v1/reports?format=csv&include=metadata`) | Modifies response shape without altering resource location | Low |
| Multi-tenant routing | Path Segment (`/v1/:tenantId/dashboard`) | Tenant context is mandatory for resource resolution, affects security boundaries | Medium (requires auth middleware) |

### Configuration Template

```typescript
// src/middleware/routing-validators.ts
import { Request, Response, NextFunction } from 'express';

export function enforcePathParams(required: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    const missing = required.filter(p => !req.params[p]?.trim());
    if (missing.length) {
      return res.status(400).json({ code: 'MISSING_PATH_PARAM', fields: missing });
    }
    next();
  };
}

export function sanitizeQuery(allowedKeys: string[], typeMap: Record<string, 'string' | 'number' | 'boolean'>) {
  return (req: Request, res: Response, next: NextFunction) => {
    const unknown = Object.keys(req.query).filter(k => !allowedKeys.includes(k));
    if (unknown.length) {
      return res.status(400).json({ code: 'UNKNOWN_QUERY_PARAM', fields: unknown });
    }

    for (const [key, type] of Object.entries(typeMap)) {
      const val = req.query[key];
      if (val !== undefined) {
        if (type === 'number' && isNaN(Number(val))) {
          return res.status(400).json({ code: 'INVALID_QUERY_TYPE', field: key, expected: 'number' });
        }
        if (type === 'boolean' && !['true', 'false'].includes(String(val).toLowerCase())) {
          return res.status(400).json({ code: 'INVALID_QUERY_TYPE', field: key, expected: 'boolean' });
        }
      }
    }
    next();
  };
}

// src/routes/catalog.ts
import { Router } from 'express';
import { enforcePathParams, sanitizeQuery } from '../middleware/routing-validators';

const catalogRouter = Router();

catalogRouter.get(
  '/v1/catalog',
  sanitizeQuery(['category', 'minPrice', 'maxPrice', 'page', 'limit', 'sort'], {
    minPrice: 'number', maxPrice: 'number', page: 'number', limit: 'number'
  }),
  async (req, res) => { /* collection handler */ }
);

catalogRouter.get(
  '/v1/catalog/:sku',
  enforcePathParams(['sku']),
  async (req, res) => { /* single resource handler */ }
);

export default catalogRouter;

Quick Start Guide

1. Initialize Router Structure: Create separate route files for collection endpoints and single-resource endpoints. Avoid mixing both in the same file to enforce semantic boundaries.
2. Define Validation Middleware: Copy the enforcePathParams and sanitizeQuery templates. Adjust allowed keys and type maps to match your domain model.
3. Apply Middleware to Routes: Attach path validation to identifier routes and query sanitization to collection routes. Ensure handlers remain focused on data fetching and response formatting.
4. Test Edge Cases: Send requests with missing path segments, malformed query values, unknown parameters, and boundary conditions. Verify that validation middleware returns consistent 400 responses before hitting business logic.
5. Document the Contract: Update your OpenAPI specification to mark path parameters as required: true and query parameters as required: false. Include examples demonstrating correct usage patterns for frontend and partner integrations.