Express API Pitfalls Skill

Express API Pitfalls

Common pitfalls and correct patterns for Express APIs.

When to Use

Building REST API routes
Implementing storage interfaces
Setting HTTP status codes
Validating request bodies
Reviewing Express API code

Workflow

Step 1: Verify Route Structure

Check that routes follow REST conventions.

Step 2: Check Status Codes

Ensure correct status codes for each operation.

Step 3: Verify Validation

Confirm input validation middleware is in place.

Route Structure

// Public routes
GET  /api/resource          // List
GET  /api/resource/:id      // Get one

// Admin routes (with auth middleware)
POST   /api/admin/resource      // Create (201)
PATCH  /api/admin/resource/:id  // Update (200)
DELETE /api/admin/resource/:id  // Delete (204)

// ✅ Always validate before storage
router.post('/', validateBody(schema), async (req, res) => {
  const validated = req.body; // Already validated by middleware
});

Status Codes

| Operation | Success | Not Found | Invalid | |-----------|---------|-----------|---------| | GET | 200 | 404 | 400 | | POST | 201 | - | 400 | | PATCH | 200 | 404 | 400 | | DELETE | 204 | 404 | - |

Storage Interface Pattern

// ✅ Define interface for all storage operations
interface IStorage {
  // Strategies
  getStrategies(): Promise<Strategy[]>;
  getStrategy(id: string): Promise<Strategy | undefined>;
  createStrategy(data: NewStrategy): Promise<Strategy>;
  updateStrategy(id: string, data: Partial<Strategy>): Promise<Strategy | undefined>;
  deleteStrategy(id: string): Promise<boolean>;
}

// ✅ Implement for different backends
class DbStorage implements IStorage { ... }  // PostgreSQL
class MemStorage implements IStorage { ... } // Testing

Background Job Patterns

// ✅ Cleanup on process exit
const intervals: NodeJS.Timeout[] = [];

function startJob(fn: () => void, ms: number) {
  const id = setInterval(fn, ms);
  intervals.push(id);
  return id;
}

process.on('SIGTERM', () => {
  intervals.forEach(clearInterval);
  process.exit(0);
});

// ✅ Handle overlapping executions
let isRunning = false;
async function scanForOpportunities() {
  if (isRunning) return;
  isRunning = true;
  try {
    await scan();
  } finally {
    isRunning = false;
  }
}

Quick Checklist

[ ] Routes follow REST conventions
[ ] Correct status codes returned
[ ] Input validation on all endpoints
[ ] Storage interface abstraction used
[ ] Background jobs handle cleanup

Agent Skills: Express API Pitfalls

Install this agent skill to your local

Skill Files