API Patterns

API Patterns

Authentication

JWT Token Structure

interface JWTPayload {
  sub: string;        // User ID
  email: string;
  role: 'user' | 'admin';
  iat: number;
  exp: number;
}

Auth Middleware

// Always use authMiddleware for protected routes
import { authMiddleware } from '@/middleware/auth';

router.get('/protected', authMiddleware, handler);

Error Handling

Standard Error Codes

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": { "field": "email" }
  }
}

Pagination

Request

GET /api/users?page=1&limit=20&sort=createdAt&order=desc

Response

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Rate Limiting

• Authenticated: 1000 requests/hour
• Unauthenticated: 100 requests/hour
• Endpoint-specific limits in src/config/rateLimit.ts

Validation

Use Zod for all request validation:

import { z } from 'zod';

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  password: z.string().min(8),
});

Converted and distributed by TomeVault — claim your Tome and manage your conversions.