Backend API

This Skill provides Claude Code with specific guidance on how it should handle backend API.

When to use this skill:

• Creating new API endpoints in server/index.ts
• Modifying request handlers or route definitions
• Implementing request validation and error responses
• Setting up Server-Sent Events (SSE) for progress streaming
• Handling async operations in Express routes
• Defining JSON response formats

Instructions

• Express Routes: Define routes in server/index.ts with clear handler separation
• HTTP Status Codes: Return appropriate codes: 200 (success), 201 (created), 400 (bad request), 404 (not found), 500 (server error)
• Error Responses: Return consistent JSON error format: { error: string, details?: any }
• Request Validation: Validate request bodies early with TypeScript types from src/lib/types.ts
• Server-to-Server Design: This is a backend microservice API for Cawpile.org, not user-facing
• Health Checks: Maintain /health endpoint for monitoring and orchestration
• Progress Streaming: Use SSE (Server-Sent Events) for long-running operations like video renders
• Async Handlers: Use async/await pattern; wrap handlers with error catching middleware

Examples:

// Good: Clear validation, proper types, error handling
app.post('/render', async (req, res) => {
  try {
    const request: RenderRequest = req.body;
    if (!request.month || !request.year) {
      return res.status(400).json({ error: 'Missing month or year' });
    }
    const result = await renderVideo(request);
    res.json({ url: result.s3Url, duration: result.duration });
  } catch (error) {
    res.status(500).json({ error: 'Render failed', details: error.message });
  }
});

// Bad: No validation, unclear error handling
app.post('/render', (req, res) => {
  renderVideo(req.body).then(r => res.json(r));
});