Skip to content

Backend API Overview

The Federated Learning Platform backend is built with FastAPI, providing a high-performance, async-capable REST API that orchestrates federated learning workflows, manages user authentication, and coordinates distributed training across multiple devices.

API Architecture

graph TB
    subgraph "API Gateway Layer"
        NGINX[Nginx Reverse Proxy]
        CORS[CORS Middleware]
        RATE_LIMIT[Rate Limiting]
    end

    subgraph "FastAPI Application"
        MAIN[main.py<br/>Application Entry]

        subgraph "Route Modules"
            AUTH_ROUTES[auth.py<br/>Authentication]
            TRAINING_ROUTES[training.py<br/>Training Management]
            NODES_ROUTES[nodes.py<br/>Node Management]
            ANSIBLE_ROUTES[ansible.py<br/>Infrastructure]
            PROJECT_ROUTES[project.py<br/>Project Management]
            WS_ROUTES[websocket.py<br/>Real-time Updates]
        end

        subgraph "Middleware Stack"
            AUTH_MIDDLEWARE[Authentication Middleware]
            LOGGING_MIDDLEWARE[Logging Middleware]
            ERROR_MIDDLEWARE[Error Handling Middleware]
            METRICS_MIDDLEWARE[Metrics Middleware]
        end

        subgraph "Service Layer"
            AUTH_SERVICE[Authentication Service]
            TRAINING_SERVICE[Training Service]
            ANSIBLE_SERVICE[Ansible Service]
            PROJECT_SERVICE[Project Service]
            WS_SERVICE[WebSocket Service]
        end
    end

    subgraph "Data Layer"
        MONGODB[(MongoDB)]
        REDIS[(Redis Cache)]
        FILE_SYSTEM[File System]
    end

    subgraph "External Services"
        FLOWER[Flower FL Framework]
        ANSIBLE_EXEC[Ansible Execution]
        OTEL[OpenTelemetry]
    end

    NGINX --> CORS
    CORS --> RATE_LIMIT
    RATE_LIMIT --> MAIN

    MAIN --> AUTH_ROUTES
    MAIN --> TRAINING_ROUTES
    MAIN --> NODES_ROUTES
    MAIN --> ANSIBLE_ROUTES
    MAIN --> PROJECT_ROUTES
    MAIN --> WS_ROUTES

    AUTH_ROUTES --> AUTH_MIDDLEWARE
    TRAINING_ROUTES --> LOGGING_MIDDLEWARE
    NODES_ROUTES --> ERROR_MIDDLEWARE
    ANSIBLE_ROUTES --> METRICS_MIDDLEWARE

    AUTH_ROUTES --> AUTH_SERVICE
    TRAINING_ROUTES --> TRAINING_SERVICE
    ANSIBLE_ROUTES --> ANSIBLE_SERVICE
    PROJECT_ROUTES --> PROJECT_SERVICE
    WS_ROUTES --> WS_SERVICE

    AUTH_SERVICE --> MONGODB
    TRAINING_SERVICE --> MONGODB
    PROJECT_SERVICE --> MONGODB
    AUTH_SERVICE --> REDIS
    PROJECT_SERVICE --> FILE_SYSTEM

    TRAINING_SERVICE --> FLOWER
    ANSIBLE_SERVICE --> ANSIBLE_EXEC
    AUTH_SERVICE --> OTEL
    TRAINING_SERVICE --> OTEL

Core API Endpoints

Authentication Endpoints

POST /auth/register

Register a new user account.

Request Body: 

{
  "username": "string",
  "email": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string"
}

Response: 

{
  "id": "string",
  "username": "string",
  "email": "string",
  "created_at": "2024-01-01T00:00:00Z"
}

POST /auth/login

Authenticate user and return JWT token.

Request Body: 

{
  "username": "string",
  "password": "string",
  "mfa_token": "string"
}

Response: 

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "string",
    "username": "string",
    "email": "string",
    "roles": ["user"]
  }
}

Training Management Endpoints

POST /training/start

Start a new federated learning training job.

Request Body: 

{
  "project_id": "string",
  "config": {
    "rounds": 10,
    "clients": 5,
    "model_type": "cnn",
    "learning_rate": 0.01,
    "batch_size": 32
  }
}

Response: 

{
  "job_id": "string",
  "status": "initializing",
  "created_at": "2024-01-01T00:00:00Z",
  "config": {
    "rounds": 10,
    "clients": 5,
    "model_type": "cnn"
  }
}

GET /training/jobs/{job_id}

Get training job status and metrics.

Response: 

{
  "job_id": "string",
  "status": "running",
  "progress": {
    "current_round": 3,
    "total_rounds": 10,
    "completion_percentage": 30
  },
  "metrics": {
    "accuracy": 0.85,
    "loss": 0.23,
    "clients_participated": 4
  },
  "started_at": "2024-01-01T00:00:00Z",
  "estimated_completion": "2024-01-01T01:00:00Z"
}

POST /training/stop/{job_id}

Stop a running training job.

Response: 

{
  "job_id": "string",
  "status": "stopped",
  "stopped_at": "2024-01-01T00:30:00Z",
  "final_metrics": {
    "accuracy": 0.82,
    "loss": 0.28,
    "rounds_completed": 3
  }
}

Project Management Endpoints

GET /projects

List user's projects with pagination.

Query Parameters: - page: Page number (default: 1) - limit: Items per page (default: 20) - search: Search term for project name/description

Response: 

{
  "projects": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "status": "active",
      "training_jobs_count": 5
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

POST /projects

Create a new project.

Request Body: 

{
  "name": "string",
  "description": "string",
  "configuration": {
    "model_type": "cnn",
    "dataset": "fashion_mnist",
    "privacy_settings": {
      "differential_privacy": false,
      "secure_aggregation": true
    }
  }
}

POST /projects/{project_id}/upload

Upload ML project configuration files.

Request: Multipart form data with ZIP file

Response: 

{
  "project_id": "string",
  "upload_id": "string",
  "status": "uploaded",
  "files": [
    "pyproject.toml",
    "client_app.py",
    "server_app.py",
    "task.py"
  ],
  "validation_status": "valid"
}

Infrastructure Management Endpoints

GET /ansible/configs

List Ansible configurations for aggregators and clients.

Response: 

{
  "configs": [
    {
      "id": "string",
      "name": "string",
      "type": "aggregator",
      "host": "192.168.1.100",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /ansible/deploy

Deploy configurations to target devices.

Request Body: 

{
  "config_ids": ["string"],
  "deployment_type": "all",
  "force_update": false
}

Response: 

{
  "deployment_id": "string",
  "status": "started",
  "targets": [
    {
      "config_id": "string",
      "host": "192.168.1.100",
      "status": "deploying"
    }
  ]
}

GET /ansible/jobs/{job_id}

Get Ansible deployment job status.

Response: 

{
  "job_id": "string",
  "status": "completed",
  "started_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:05:00Z",
  "results": [
    {
      "host": "192.168.1.100",
      "status": "success",
      "tasks_completed": 15,
      "tasks_failed": 0
    }
  ]
}

Node Management Endpoints

GET /nodes

List connected federated learning nodes.

Response: 

{
  "nodes": [
    {
      "id": "string",
      "type": "aggregator",
      "host": "192.168.1.100",
      "status": "connected",
      "last_seen": "2024-01-01T00:00:00Z",
      "metrics": {
        "cpu_usage": 45.2,
        "memory_usage": 67.8,
        "disk_usage": 23.1
      }
    }
  ]
}

GET /nodes/{node_id}/metrics

Get detailed metrics for a specific node.

Response: 

{
  "node_id": "string",
  "metrics": {
    "system": {
      "cpu_usage": 45.2,
      "memory_usage": 67.8,
      "disk_usage": 23.1,
      "network_io": {
        "bytes_sent": 1024000,
        "bytes_received": 2048000
      }
    },
    "federated_learning": {
      "training_rounds_completed": 5,
      "model_updates_sent": 10,
      "average_training_time": 120.5
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

API Response Patterns

Standard Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": {},
  "message": "Operation completed successfully",
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "uuid"
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "uuid"
}

Pagination Format

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Authentication and Authorization

JWT Token Structure

{
  "sub": "username",
  "user_id": "uuid",
  "email": "user@example.com",
  "roles": ["user"],
  "permissions": ["read:projects", "write:projects"],
  "iat": 1640995200,
  "exp": 1640998800,
  "type": "access"
}

Authorization Headers

All protected endpoints require the Authorization header:

Authorization: Bearer <jwt_token>

Role-Based Permissions

Role Permissions
admin All permissions
user read:projects, write:projects, start:training, view:metrics
viewer read:projects, view:metrics

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Rate Limit Policies

Endpoint Category Rate Limit
Authentication 5 requests/minute
General API 100 requests/minute
File Upload 10 requests/minute
Training Operations 20 requests/minute

WebSocket API

Connection Endpoint

ws://localhost:8000/ws/{user_id}

Message Format

{
  "type": "training_update",
  "data": {
    "job_id": "string",
    "status": "running",
    "progress": 45,
    "metrics": {
      "accuracy": 0.85,
      "loss": 0.23
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Event Types

  • training_update: Training job progress updates
  • node_status: Node connection status changes
  • deployment_status: Ansible deployment progress
  • system_alert: System-wide notifications

Error Handling

HTTP Status Codes

Code Description Usage
200 OK Successful GET, PUT, PATCH
201 Created Successful POST
204 No Content Successful DELETE
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource not found
409 Conflict Resource already exists
422 Unprocessable Entity Validation errors
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side errors

Error Codes

Code Description
VALIDATION_ERROR Input validation failed
AUTHENTICATION_FAILED Invalid credentials
AUTHORIZATION_FAILED Insufficient permissions
RESOURCE_NOT_FOUND Requested resource not found
RESOURCE_CONFLICT Resource already exists
RATE_LIMIT_EXCEEDED Too many requests
TRAINING_ERROR Federated learning operation failed
DEPLOYMENT_ERROR Ansible deployment failed
INTERNAL_ERROR Unexpected server error

API Versioning

Version Header

API-Version: v1

Versioned Endpoints

/v1/auth/login
/v1/training/start
/v1/projects

Deprecation Notice

Deprecation: true
Sunset: 2024-12-31T23:59:59Z
Link: </v2/auth/login>; rel="successor-version"

Next: Continue to Authentication for detailed authentication and security implementation.