Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
635 lines (507 loc) · 12.3 KB

API_DOCUMENTATION.md

File metadata and controls

635 lines (507 loc) · 12.3 KB
Raw

Godis Distributed AI Training Platform - API Documentation

Overview

The Godis platform provides a comprehensive API for distributed AI training, resource sharing, points system, and model management. All authenticated endpoints require a JWT token in the Authorization header.

Base URL

http://localhost:8080

Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <your_jwt_token>

🔐 Authentication Endpoints

Register User

POST /api/auth/register

Register a new user account.

Request Body:

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "secure_password123"
}

Response:

{
  "message": "User registered successfully"
}

Login

POST /api/auth/login

Authenticate and receive JWT token.

Request Body:

{
  "username": "john_doe",
  "password": "secure_password123"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

🖥️ Node Management Endpoints

Register Node

POST /api/nodes/register

Register a compute node to share resources.

Headers: Authorization: Bearer <token>

Request Body:

{
  "address": "127.0.0.1:9001",
  "cpu": 8,
  "ram": 17179869184,
  "gpu": 2
}

Response:

{
  "message": "Node registered successfully",
  "node": {
    "ID": 1,
    "owner_id": 3,
    "address": "127.0.0.1:9001",
    "is_active": true,
    "cpu": 8,
    "ram": 17179869184,
    "gpu": 2,
    "last_seen": "2025-08-06T11:14:04.462934+05:30"
  }
}

Send Heartbeat

POST /api/nodes/heartbeat

Keep node active with periodic heartbeat.

Headers: Authorization: Bearer <token>

Request Body:

{
  "address": "127.0.0.1:9001"
}

Response:

{
  "message": "Heartbeat received"
}

List Active Nodes

GET /api/nodes

Get list of all active nodes.

Headers: Authorization: Bearer <token>

Response:

[
  {
    "ID": 1,
    "owner_id": 3,
    "address": "127.0.0.1:9001",
    "is_active": true,
    "cpu": 8,
    "ram": 17179869184,
    "gpu": 2,
    "last_seen": "2025-08-06T11:14:04.462934+05:30"
  }
]

🚀 Task Management Endpoints

Submit Training Task

POST /api/tasks

Submit a distributed AI training task.

Headers: Authorization: Bearer <token>

Request Body:

{
  "name": "MNIST Classification",
  "model_url": "https://github.com/user/mnist-model.git",
  "dataset_url": "https://storage.example.com/mnist-dataset.zip",
  "entry_point": "train.py",
  "hyperparameters": "{\"learning_rate\": 0.001, \"batch_size\": 32, \"epochs\": 10}",
  "required_cpu": 4,
  "required_gpu": 1
}

Response:

{
  "message": "Task submitted successfully",
  "task": {
    "ID": 123,
    "name": "MNIST Classification",
    "user_id": 3,
    "status": "pending",
    "model_url": "https://github.com/user/mnist-model.git",
    "dataset_url": "https://storage.example.com/mnist-dataset.zip",
    "entry_point": "train.py",
    "hyperparameters": "{\"learning_rate\": 0.001, \"batch_size\": 32, \"epochs\": 10}",
    "required_cpu": 4,
    "required_gpu": 1
  }
}

Get Task Status

GET /api/tasks/{taskId}

Get status and details of a specific task.

Headers: Authorization: Bearer <token>

Response:

{
  "ID": 123,
  "name": "MNIST Classification",
  "user_id": 3,
  "status": "completed",
  "model_url": "https://github.com/user/mnist-model.git",
  "dataset_url": "https://storage.example.com/mnist-dataset.zip",
  "entry_point": "train.py",
  "hyperparameters": "{\"learning_rate\": 0.001, \"batch_size\": 32, \"epochs\": 10}",
  "required_cpu": 4,
  "required_gpu": 1,
  "result_message": "Training completed - Loss: 0.0234, Accuracy: 98.50%. Model ready for download at: /api/models/123/download",
  "model_download_url": "/api/models/123/download"
}

List User Tasks

GET /api/tasks

Get list of all tasks submitted by the current user.

Headers: Authorization: Bearer <token>

Query Parameters:

  • status (optional): Filter by task status (pending, running, completed, failed)
  • limit (optional): Number of tasks to return (default: 50)
  • offset (optional): Number of tasks to skip (default: 0)

Response:

{
  "tasks": [
    {
      "ID": 123,
      "name": "MNIST Classification",
      "status": "completed",
      "created_at": "2025-08-06T10:30:00Z",
      "model_download_url": "/api/models/123/download"
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}

🧠 Training Status Endpoints

Get Training Status

GET /api/training/{taskId}/status

Get real-time training progress and status.

Headers: Authorization: Bearer <token>

Response:

{
  "task_id": "123",
  "status": "training",
  "progress": 0.75,
  "current_epoch": 8,
  "total_epochs": 10,
  "current_metrics": {
    "loss": 0.0234,
    "accuracy": 0.985
  },
  "nodes_participating": 3,
  "estimated_completion": "2025-08-06T12:45:00Z"
}

List Active Training Sessions

GET /api/training/sessions

Get list of all active training sessions.

Headers: Authorization: Bearer <token>

Response:

{
  "sessions": [
    {
      "task_id": "123",
      "status": "training",
      "progress": 0.75,
      "nodes_participating": 3,
      "start_time": "2025-08-06T11:00:00Z"
    }
  ],
  "count": 1
}

📦 Model Management Endpoints

Download Trained Model

GET /api/models/{taskId}/download

Download the final trained model file.

Headers: Authorization: Bearer <token>

Response: Binary file download (PyTorch .pth file)

Get Model Information

GET /api/models/{taskId}/info

Get information about a trained model.

Headers: Authorization: Bearer <token>

Response:

{
  "task_id": 123,
  "task_name": "MNIST Classification",
  "status": "completed",
  "model_path": "./training_workspace/123/final_model.pth",
  "file_size": 2048576,
  "created_at": "2025-08-06T12:30:00Z",
  "download_url": "/api/models/123/download",
  "message": "Model is ready for download"
}

List User Models

GET /api/models

Get list of all completed models for the current user.

Headers: Authorization: Bearer <token>

Response:

{
  "models": [
    {
      "task_id": 123,
      "task_name": "MNIST Classification",
      "status": "completed",
      "file_size": 2048576,
      "created_at": "2025-08-06T12:30:00Z",
      "download_url": "/api/models/123/download"
    }
  ],
  "count": 1
}

🏆 Points System Endpoints

Get User Points

GET /api/points/me

Get current user's points and rank.

Headers: Authorization: Bearer <token>

Response:

{
  "user_id": 3,
  "total_points": 1250,
  "rank": 5,
  "user": {
    "ID": 3,
    "username": "john_doe",
    "email": "john@example.com"
  }
}

Get Points Transaction History

GET /api/points/me/transactions

Get user's points earning and spending history.

Headers: Authorization: Bearer <token>

Query Parameters:

  • limit (optional): Number of transactions to return (default: 50, max: 100)
  • offset (optional): Number of transactions to skip (default: 0)

Response:

{
  "transactions": [
    {
      "ID": 456,
      "user_id": 3,
      "points": 80,
      "type": "resource_sharing",
      "description": "Resource sharing: 4 CPU, 1 GPU, 16.0 GB RAM for 2.00 hours",
      "created_at": "2025-08-06T10:00:00Z"
    },
    {
      "ID": 457,
      "user_id": 3,
      "points": 50,
      "type": "task_completion",
      "description": "Task completion bonus for task #123",
      "created_at": "2025-08-06T12:30:00Z"
    },
    {
      "ID": 458,
      "user_id": 3,
      "points": -20,
      "type": "task_submission",
      "description": "Task submission fee for task #124",
      "created_at": "2025-08-06T13:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "count": 3
}

Get User Rank

GET /api/points/me/rank

Get detailed rank information and statistics for current user.

Headers: Authorization: Bearer <token>

Response:

{
  "user_id": 3,
  "username": "john_doe",
  "total_points": 1250,
  "rank": 5,
  "tasks_shared": 8,
  "tasks_run": 15,
  "uptime_hours": 125.5,
  "joined_at": "2025-07-01T09:00:00Z"
}

🥇 Leaderboard Endpoints

Get Global Leaderboard

GET /api/leaderboard/

Get the global points leaderboard.

Headers: Authorization: Bearer <token>

Query Parameters:

  • limit (optional): Number of users to return (default: 50, max: 100)
  • offset (optional): Number of users to skip (default: 0)

Response:

{
  "leaderboard": [
    {
      "user_id": 1,
      "username": "alice_ai",
      "total_points": 5420,
      "rank": 1,
      "tasks_shared": 25,
      "tasks_run": 45,
      "uptime_hours": 542.0,
      "joined_at": "2025-06-01T08:00:00Z"
    },
    {
      "user_id": 2,
      "username": "bob_compute",
      "total_points": 3890,
      "rank": 2,
      "tasks_shared": 18,
      "tasks_run": 32,
      "uptime_hours": 389.0,
      "joined_at": "2025-06-15T14:30:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "count": 2
}

Get Top Users

GET /api/leaderboard/top

Get the top N users by points.

Headers: Authorization: Bearer <token>

Query Parameters:

  • limit (optional): Number of top users to return (default: 10, max: 50)

Response:

{
  "top_users": [
    {
      "user_id": 1,
      "username": "alice_ai",
      "total_points": 5420,
      "rank": 1,
      "tasks_shared": 25,
      "tasks_run": 45,
      "uptime_hours": 542.0,
      "joined_at": "2025-06-01T08:00:00Z"
    }
  ],
  "count": 1
}

⚙️ Admin & Stats Endpoints

Update Leaderboard (Admin)

POST /api/admin/leaderboard/update

Manually trigger leaderboard recalculation.

Headers: Authorization: Bearer <admin_token>

Response:

{
  "message": "Leaderboard updated successfully"
}

Get Points System Stats

GET /api/points/stats

Get points system configuration and statistics (public endpoint).

Response:

{
  "points_config": {
    "cpu_points_per_hour": 10,
    "gpu_points_per_hour": 100,
    "memory_points_per_gb": 1,
    "task_completion_bonus": 50,
    "uptime_bonus_threshold": 24,
    "uptime_bonus_points": 100,
    "task_submission_cost": 20,
    "priority_boost_cost": 50
  },
  "message": "Points system is active"
}

📊 Points System Rules

Earning Points

Action Points Earned Description
CPU Sharing 10 points/hour/core Per CPU core shared
GPU Sharing 100 points/hour/unit Per GPU unit shared
RAM Sharing 1 point/hour/GB Per GB RAM shared
Task Completion 50 points Bonus for completing training tasks
Uptime Bonus 100 points After 24+ hours continuous operation

Spending Points

Action Points Cost Description
Task Submission 20 points Cost to submit a training task
Priority Boost 50 points Move task to front of queue

🔄 Typical Workflow

  1. Register & Login → Get JWT token
  2. Share Resources → Register node with --docker flag
  3. Earn Points → Automatic points for resource sharing
  4. Submit Tasks → Pay points to submit AI training tasks
  5. Monitor Training → Check progress via training status APIs
  6. Download Models → Get trained models when complete
  7. Check Leaderboard → See your rank and compete with others

🚨 Error Responses

All endpoints return appropriate HTTP status codes and error messages:

{
  "error": "Insufficient points: user has 15, trying to deduct 20"
}

Common status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

🛠️ CLI Usage

Share Resources with Docker

./build/godis share --cpu 4 --gpu 1 --docker --port 9001

Login via CLI

./build/godis login

Check System Benchmark

./build/godis benchmark

This comprehensive API enables building powerful distributed AI training applications with gamification, resource sharing, and model management capabilities!