api-patterns

# API Patterns Skill

## Quick Reference

**Use when**: Building REST APIs, implementing authentication, handling errors, validating inputs

**Key Patterns**:
- Request validation
- Standardized error responses
- Authentication middleware
- Rate limiting
- Pagination
- API documentation

---

## 1. Request Validation

**Always validate incoming requests at the boundary.**

Pattern with schema validation:
```typescript
// Define schema for expected input
const CreateUserSchema = {
  email: 'string, email format, required',
  password: 'string, min 12 chars, required',
  name: 'string, 2-100 chars, required',
  age: 'number, integer, min 18, optional'
};

// Validate in route handler
function createUserHandler(req, res) {
  const validation = validateSchema(CreateUserSchema, req.body);

  if (!validation.success) {
    return res.status(400).json({
      error: 'Validation failed',
      details: validation.errors
    });
  }

  // Proceed with validated data
  const user = await createUser(validation.data);
  res.status(201).json(user);
}
```

**Key Points**:
- Validate at API boundary, not deep in business logic
- Return specific error messages
- Use 400 status code for validation failures

---

## 2. Standardized Error Responses

**Use consistent error format across all endpoints.**

```typescript
// Error response structure
interface ErrorResponse {
  error: string;        // Human-readable message
  code?: string;        // Machine-readable error code
  details?: unknown;    // Additional context (validation errors, etc.)
}

// Custom error class
class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number = 500,
    public code?: string,
    public details?: unknown
  ) {
    super(message);
  }
}

// Usage
throw new AppError('User not found', 404, 'USER_NOT_FOUND');
throw new AppError('Validation failed', 400, 'VALIDATION_ERROR', errors);
```

**Error Handler Pattern**:
```typescript
function errorHandler(err, req, res, next)