EDURange Cloud API Documentation

This documentation provides a comprehensive overview of the EDURange Cloud API endpoints.

Overview

The EDURange Cloud API is organized into the following categories:

• Authentication - User authentication and session management
• Users - User management and profile operations
• Competitions - Competition creation, management, and participation
• Challenges - Challenge management and interaction
• Proxy Endpoints - Internal service communication endpoints
• Admin Operations - Administrative functions and system management
• System Health - System monitoring and health checks

Common Features

Authentication

All API routes require authentication unless explicitly stated. Authentication is handled through NextAuth.js sessions.

Rate Limiting

EDURange Cloud implements rate limiting to protect the API from abuse and ensure fair usage. The rate limiting system:

• Tracks requests based on IP address by default
• Returns a 429 Too Many Requests status code when limits are exceeded
• Includes a Retry-After header indicating when to try again
• Uses different limits for different endpoint types based on sensitivity

Rate Limit Configuration

Rate-limited endpoints are marked with 🔒 in this documentation.

Input Validation

EDURange Cloud implements comprehensive input validation to ensure data integrity and prevent security vulnerabilities:

• All user inputs are validated using Zod schemas and sanitized using the validateAndSanitize function
• Input validation failures return a 400 Bad Request status code with detailed error messages
• String inputs are sanitized to prevent XSS attacks
• Common validation schemas are reused across endpoints for consistency
• Nested objects are validated at each level of the hierarchy
• Validation is performed before any database operations

The validation system provides the following benefits:

• Security: Prevents injection attacks and malicious inputs
• Data Integrity: Ensures data meets expected formats and constraints
• Error Handling: Provides clear error messages for invalid inputs
• Consistency: Applies the same validation rules across all endpoints

Common Validation Rules

Validation Implementation

All API endpoints use a standardized validation approach:

// Import the validation utilities
import { validateAndSanitize, validationSchemas } from '@/lib/validation';
 
// Define a schema using Zod
const mySchema = z.object({
  name: validationSchemas.name,
  email: validationSchemas.email,
  // Other fields...
});
 
// In your API route handler:
const validationResult = validateAndSanitize(mySchema, requestData);
 
if (!validationResult.success) {
  return NextResponse.json({ 
    success: false, 
    error: validationResult.error 
  }, { status: 400 });
}
 
// Use the validated and sanitized data
const { name, email } = validationResult.data;

Endpoints with input validation will include a note about the validation being performed.

Error Handling

All API endpoints follow a consistent error response format:

{
  "error": "Error message description"
}

Common HTTP status codes:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Too Many Requests
• 500: Internal Server Error