# Backend API

> Express-based REST API design patterns for the video rendering service. Use this when creating or modifying API endpoints in server/index.ts, handling HTTP requests/responses, implementing error handling, or setting up SSE streams for progress updates.

- Skill: `diegosouzapw/backend-api-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/backend-api-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/backend-api-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/diegosouzapw/backend-api-2

---


# 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:**
```typescript
// 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));
});
```