REST API Expert

# Check for API framework
grep -r "express\|fastify\|koa\|nestjs\|hono" package.json 2>/dev/null

# Check for OpenAPI/Swagger
ls -la swagger.* openapi.* 2>/dev/null
find . -name "*.yaml" -o -name "*.json" | xargs grep -l "openapi" 2>/dev/null | head -3

# Check existing API routes
find . -type f \( -name "*.ts" -o -name "*.js" \) -path "*/routes/*" -o -path "*/controllers/*" | head -10

// ❌ BAD: Verb-based endpoints
GET    /getUsers
POST   /createUser
PUT    /updateUser/123
DELETE /deleteUser/123
GET    /getUserOrders/123

// ✅ GOOD: Resource-based endpoints
GET    /users              # List users
POST   /users              # Create user
GET    /users/123          # Get user
PUT    /users/123          # Update user (full)
PATCH  /users/123          # Update user (partial)
DELETE /users/123          # Delete user
GET    /users/123/orders   # User's orders (nested resource)

// ✅ GOOD: Filtering, sorting, pagination
GET    /users?status=active&sort=-createdAt&page=2&limit=20

// ✅ GOOD: Search as sub-resource
GET    /users/search?q=john&fields=name,email

// ✅ GOOD: Actions as sub-resources (when needed)
POST   /users/123/activate    # Action on resource
POST   /orders/456/cancel     # State transition

// Method characteristics
// GET     - Safe, Idempotent, Cacheable
// POST    - Not Safe, Not Idempotent
// PUT     - Not Safe, Idempotent
// PATCH   - Not Safe, Not Idempotent
// DELETE  - Not Safe, Idempotent

// Express example with proper methods
import { Router } from 'express';

const router = Router();

// GET - Retrieve resources (safe, idempotent)
router.get('/products', listProducts);
router.get('/products/:id', getProduct);

// POST - Create resources (not idempotent)
router.post('/products', createProduct);

// PUT - Replace entire resource (idempotent)
router.put('/products/:id', replaceProduct);

// PATCH - Partial update (not idempotent typically)
router.patch('/products/:id', updateProduct);

// DELETE - Remove resource (idempotent)
router.delete('/products/:id', deleteProduct);

// 2xx Success
200 OK              // GET success, PUT/PATCH success with body
201 Created         // POST success (include Location header)
204 No Content      // DELETE success, PUT/PATCH success without body

// 3xx Redirection
301 Moved Permanently  // Resource URL changed permanently
304 Not Modified       // Cached response is still valid

// 4xx Client Errors
400 Bad Request     // Invalid request body/params
401 Unauthorized    // Missing or invalid authentication
403 Forbidden       // Authenticated but not authorized
404 Not Found       // Resource doesn't exist
405 Method Not Allowed  // HTTP method not supported
409 Conflict        // State conflict (e.g., duplicate)
422 Unprocessable Entity  // Validation errors
429 Too Many Requests    // Rate limit exceeded

// 5xx Server Errors
500 Internal Server Error  // Unexpected server error
502 Bad Gateway           // Upstream service error
503 Service Unavailable   // Temporary overload/maintenance

// Error response structure
interface ApiError {
  status: number;          // HTTP status code
  code: string;            // Application-specific error code
  message: string;         // Human-readable message
  details?: ErrorDetail[]; // Field-level errors (for validation)
  requestId?: string;      // For debugging/support
  timestamp?: string;      // ISO 8601
}

interface ErrorDetail {
  field: string;
  message: string;
  code: string;
}

// Example responses
// 400 Bad Request - Validation Error
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    { "field": "email", "message": "Invalid email format", "code": "INVALID_EMAIL" },
    { "field": "age", "message": "Must be at least 18", "code": "MIN_VALUE" }
  ],
  "requestId": "req_abc123",
  "timestamp": "2024-01-15T10:30:00Z"
}

// 404 Not Found
{
  "status": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "User with ID '123' not found",
  "requestId": "req_def456",
  "timestamp": "2024-01-15T10:30:00Z"
}

// 500 Internal Server Error
{
  "status": 500,
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Please try again later.",
  "requestId": "req_ghi789",
  "timestamp": "2024-01-15T10:30:00Z"
}

// Express error handler
import { Request, Response, NextFunction } from 'express';

class AppError extends Error {
  constructor(
    public status: number,
    public code: string,
    message: string,
    public details?: ErrorDetail[]
  ) {
    super(message);
  }
}

function errorHandler(
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction
) {
  const requestId = req.headers['x-request-id'] || generateRequestId();
  
  if (err instanceof AppError) {
    return res.status(err.status).json({
      status: err.status,
      code: err.code,
      message: err.message,
      details: err.details,
      requestId,
      timestamp: new Date().toISOString(),
    });
  }
  
  // Log unexpected errors
  console.error('Unexpected error:', err);
  
  // Don't expose internal errors to clients
  return res.status(500).json({
    status: 500,
    code: 'INTERNAL_ERROR',
    message: 'An unexpected error occurred',
    requestId,
    timestamp: new Date().toISOString(),
  });
}

// 1. Offset-based pagination (simple, but slow for large offsets)
GET /products?page=2&limit=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true
  }
}

// 2. Cursor-based pagination (efficient for large datasets)
GET /products?cursor=eyJpZCI6MTAwfQ&limit=20

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "nextCursor": "eyJpZCI6MTIwfQ",
    "prevCursor": "eyJpZCI6ODB9",
    "hasNext": true,
    "hasPrev": true
  }
}

// Implementation example
async function paginateWithCursor(
  cursor: string | null,
  limit: number = 20
) {
  const decodedCursor = cursor 
    ? JSON.parse(Buffer.from(cursor, 'base64').toString())
    : null;
    
  const items = await prisma.product.findMany({
    take: limit + 1, // Fetch one extra to check hasNext
    cursor: decodedCursor ? { id: decodedCursor.id } : undefined,
    skip: decodedCursor ? 1 : 0,
    orderBy: { id: 'asc' },
  });
  
  const hasNext = items.length > limit;
  const data = hasNext ? items.slice(0, -1) : items;
  
  return {
    data,
    pagination: {
      limit,
      nextCursor: hasNext 
        ? Buffer.from(JSON.stringify({ id: data[data.length - 1].id })).toString('base64')
        : null,
      hasNext,
    },
  };
}

// 1. URL Path Versioning (recommended)
GET /api/v1/users
GET /api/v2/users

// Implementation
import { Router } from 'express';

const v1Router = Router();
const v2Router = Router();

// V1 routes
v1Router.get('/users', getUsersV1);

// V2 routes with breaking changes
v2Router.get('/users', getUsersV2);

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

// 2. Header Versioning
GET /api/users
Accept: application/vnd.myapi.v2+json

// 3. Query Parameter (not recommended for APIs)
GET /api/users?version=2

// Communicate deprecation
res.setHeader('Deprecation', 'true');
res.setHeader('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT');
res.setHeader('Link', '</api/v2/users>; rel="successor-version"');