Api

Next.js API route handlers providing REST endpoints for system monitoring and development testing.

API Routes (app/api/)

Next.js API route handlers providing REST endpoints for system monitoring and development testing.

Purpose

REST API endpoints for:

1. System health checks and monitoring
2. Cache performance statistics
3. Development/debugging tools
4. External integrations (if needed)

API Routes vs Server Actions

The application uses Server Actions for primary user interactions (form submissions, geocoding) and API Routes for:

• External system integrations
• Webhooks and callbacks
• Non-form-based HTTP requests
• Programmatic access (curl, Postman, etc.)
• Health checks and monitoring

Routes

System Status (/api/system-status)

Health check endpoint for monitoring application and external dependencies.

Endpoint: GET /api/system-status

Query Parameters:

• checkApis (optional): Set to "true" to include external API health checks

Response Format:

interface HealthCheckResponse {
  status: "healthy" | "degraded" | "unhealthy";
  timestamp: string;
  uptime: {
    seconds: number;
    formatted: string; // e.g., "2d 5h 30m 15s"
  };
  cache: {
    enabled: boolean;
    size: number;
    maxSize: number;
    utilizationPercent: number;
  };
  externalApis?: {
    njStateApis: {
      status: "reachable" | "unreachable" | "unknown";
      responseTime?: number;
      error?: string;
    };
  };
}

Example Requests:

# Quick health check (fast, no external API calls)
curl http://localhost:3000/api/system-status

# Deep health check (includes NJ API verification)
curl http://localhost:3000/api/system-status?checkApis=true

Status Codes:

• 200 OK: System is healthy or degraded
• 503 Service Unavailable: System is unhealthy

Use Cases:

• Load balancer health checks
• Monitoring dashboard data source
• Uptime monitoring services (Pingdom, UptimeRobot, etc.)
• CI/CD pipeline verification

Response Headers

All API routes include:

• Content-Type: application/json
• Cache-Control: Appropriate caching directives
• X-Response-Time: Request processing time (in development)

Error Handling

API routes return consistent error formats:

interface ErrorResponse {
  error: string; // User-friendly message
  statusCode: number;
  timestamp: string;
}

Example Error Response:

{
  "error": "Invalid request parameters",
  "statusCode": 400,
  "timestamp": "2025-12-26T10:30:00.000Z"
}

Security

API routes implement standard security practices:

1. Rate Limiting: Enforced at adapter/middleware level
2. CORS: Configured for allowed origins
3. Input Validation: All query parameters and request bodies validated
4. Error Sanitization: No stack traces or sensitive data in responses
5. HTTPS Only: Production deployment requires HTTPS

Performance

API routes are optimized for low latency:

• System Status (quick): < 50ms response time
• System Status (deep): < 1s response time
• Zero Cold Start: App Router routes are always warm

Usage Examples

Health Check in CI/CD

# GitHub Actions example
- name: Verify deployment health
  run: |
    curl -f http://app.example.com/api/system-status || exit 1

Monitoring Dashboard Integration

// Fetch health status for dashboard
async function fetchSystemHealth() {
  const response = await fetch("/api/system-status?checkApis=true");
  const health: HealthCheckResponse = await response.json();

  return {
    isHealthy: health.status === "healthy",
    uptime: health.uptime.formatted,
    cacheUtilization: health.cache.utilizationPercent,
    apiStatus: health.externalApis?.njStateApis.status,
  };
}

Load Balancer Configuration

# NGINX health check configuration
upstream app_servers {
  server app1.example.com:3000;
  server app2.example.com:3000;

  # Health check
  health_check interval=30s uri=/api/system-status;
}

Development Tools

In development mode, additional API routes may be available for:

• Cache inspection and clearing
• Mock data generation
• API response simulation
• Performance profiling

These routes are disabled in production builds.

Testing

API routes are tested with:

1. Unit Tests: Route handler logic with mocked dependencies
2. Integration Tests: Full request/response cycle
3. E2E Tests: Playwright tests making actual HTTP requests

Example Test:

import { GET } from "@/app/api/system-status/route";

test("should return health status", async () => {
  const request = new Request("http://localhost:3000/api/system-status");
  const response = await GET(request);

  expect(response.status).toBe(200);

  const data = await response.json();
  expect(data.status).toBe("healthy");
  expect(data.cache.enabled).toBe(true);
});

Related Documentation

• system-status/ - Health check endpoint details
• Server Actions - Alternative to API routes for form handling
• Domain Use Cases - Business logic
• Adapters - External service integrations