API_DOCS.md

📡 API Documentation

Base URL

http://localhost:8000

Authentication

No authentication required for this demo version.

---

🏥 Health & Status Endpoints

GET /health

Get system health status

Request:

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00",
  "components": [
    {
      "name": "API Server 1",
      "status": "healthy",
      "uptime": 99.99,
      "response_time": 120
    }
  ],
  "summary": {
    "total_components": 8,
    "healthy": 8,
    "degraded": 0,
    "critical": 0
  }
}

---

GET /info

Get system information

Request:

curl http://localhost:8000/info

Response:

{
  "name": "Crypto API Monitor",
  "version": "1.0.0",
  "environment": "production",
  "uptime_seconds": 86400,
  "memory_usage_mb": 450,
  "cpu_usage_percent": 25.5,
  "active_connections": 3,
  "timestamp": "2025-01-15T10:30:00"
}

---

📊 Provider Endpoints

GET /api/providers

Get all data providers status

Request:

curl http://localhost:8000/api/providers

Response:

[
  {
    "name": "Binance",
    "type": "Exchange",
    "status": "operational",
    "uptime": 99.95,
    "response_time_ms": 85,
    "requests_today": 150000,
    "last_check": "2025-01-15T10:30:00",
    "endpoint": "https://api.binance.com"
  },
  {
    "name": "CoinGecko",
    "type": "Data Provider",
    "status": "operational",
    "uptime": 99.87,
    "response_time_ms": 120,
    "requests_today": 89000,
    "last_check": "2025-01-15T10:30:00",
    "endpoint": "https://api.coingecko.com"
  }
]

---

💰 Cryptocurrency Data

GET /api/crypto/prices/top

Get top cryptocurrency prices

Parameters:

• limit (optional): Number of results (default: 10)

Request:

curl http://localhost:8000/api/crypto/prices/top?limit=5

Response:

[
  {
    "symbol": "BTC",
    "name": "Bitcoin",
    "price": 42150.50,
    "change_24h": 3.25,
    "volume_24h": 28000000000,
    "market_cap": 825000000000,
    "last_updated": "2025-01-15T10:30:00"
  },
  {
    "symbol": "ETH",
    "name": "Ethereum",
    "price": 2215.80,
    "change_24h": 2.15,
    "volume_24h": 12000000000,
    "market_cap": 265000000000,
    "last_updated": "2025-01-15T10:30:00"
  }
]

---

GET /api/crypto/market-overview

Get market overview and statistics

Request:

curl http://localhost:8000/api/crypto/market-overview

Response:

{
  "total_market_cap": 1750000000000,
  "total_volume_24h": 95000000000,
  "average_change_24h": 2.45,
  "top_gainers": [
    {
      "symbol": "SOL",
      "name": "Solana",
      "price": 98.50,
      "change_24h": 12.30
    }
  ],
  "top_losers": [
    {
      "symbol": "XRP",
      "name": "Ripple",
      "price": 0.51,
      "change_24h": -5.20
    }
  ],
  "timestamp": "2025-01-15T10:30:00"
}

---

📁 Categories

GET /api/categories

Get cryptocurrency categories

Request:

curl http://localhost:8000/api/categories

Response:

[
  {
    "id": 1,
    "name": "DeFi",
    "market_cap": 45000000000,
    "change_24h": 5.2
  },
  {
    "id": 2,
    "name": "Smart Contract Platform",
    "market_cap": 120000000000,
    "change_24h": 3.1
  }
]

---

⏱️ Rate Limits

GET /api/rate-limits

Get API rate limit information

Request:

curl http://localhost:8000/api/rate-limits

Response:

[
  {
    "provider": "Binance",
    "limit_per_minute": 1200,
    "limit_per_hour": 60000,
    "remaining": 850,
    "reset_time": "2025-01-15T10:31:00"
  }
]

---

📋 Logs

GET /api/logs

Get system logs

Parameters:

• limit (optional): Number of logs (default: 50)

Request:

curl http://localhost:8000/api/logs?limit=10

Response:

[
  {
    "id": 1,
    "timestamp": "2025-01-15T10:30:00",
    "level": "INFO",
    "message": "API request processed successfully",
    "provider": "Binance"
  },
  {
    "id": 2,
    "timestamp": "2025-01-15T10:29:45",
    "level": "WARNING",
    "message": "Rate limit approaching",
    "provider": "CoinGecko"
  }
]

---

🔔 Alerts

GET /api/alerts

Get active system alerts

Request:

curl http://localhost:8000/api/alerts

Response:

[
  {
    "id": 1,
    "severity": "warning",
    "title": "High API Usage",
    "message": "API usage is at 85% of limit",
    "timestamp": "2025-01-15T10:30:00"
  }
]

---

🤗 Hugging Face Integration

GET /api/hf/health

Check Hugging Face integration health

Request:

curl http://localhost:8000/api/hf/health

Response:

{
  "status": "operational",
  "models_available": 12,
  "last_sync": "2025-01-15T10:30:00"
}

---

POST /api/hf/refresh

Refresh Hugging Face data

Request:

curl -X POST http://localhost:8000/api/hf/refresh

Response:

{
  "status": "success",
  "message": "Data refresh initiated",
  "timestamp": "2025-01-15T10:30:00"
}

---

GET /api/hf/registry

Get Hugging Face model registry

Request:

curl http://localhost:8000/api/hf/registry

Response:

{
  "models": [
    {
      "name": "sentiment-analysis",
      "status": "active"
    },
    {
      "name": "price-prediction",
      "status": "active"
    }
  ]
}

---

POST /api/hf/run-sentiment

Run sentiment analysis

Request:

curl -X POST http://localhost:8000/api/hf/run-sentiment \
  -H "Content-Type: application/json" \
  -d '{"text": "Bitcoin is going to the moon!"}'

Response:

{
  "sentiment": "positive",
  "score": 0.95,
  "timestamp": "2025-01-15T10:30:00"
}

---

🔌 WebSocket

WS /ws/live

Real-time updates via WebSocket

Connection:

const ws = new WebSocket('ws://localhost:8000/ws/live');

ws.onopen = () => {
  console.log('Connected');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Message:', data);
};

Message Types:

Connection Established

{
  "type": "connection_established",
  "timestamp": "2025-01-15T10:30:00"
}

Status Update

{
  "type": "status_update",
  "data": {
    "status": "healthy",
    "components": [...]
  },
  "timestamp": "2025-01-15T10:30:00"
}

Provider Status Change

{
  "type": "provider_status_change",
  "data": {
    "provider": "Binance",
    "status": "operational"
  },
  "timestamp": "2025-01-15T10:30:00"
}

New Alert

{
  "type": "new_alert",
  "data": {
    "severity": "info",
    "title": "System Update",
    "message": "Cache refreshed successfully"
  },
  "timestamp": "2025-01-15T10:30:00"
}

---

📊 Status Codes

• 200 - Success
• 404 - Endpoint not found
• 500 - Internal server error

---

🔄 Update Frequency

• WebSocket: Real-time (every 5 seconds)
• Health: On-demand
• Providers: On-demand
• Crypto Prices: On-demand (recommended: every 30s)

---

💡 Best Practices

1. Use WebSocket for real-time data instead of polling
2. Cache responses when appropriate
3. Respect rate limits to avoid throttling
4. Handle errors gracefully with retry logic
5. Monitor health endpoint regularly

---

🧪 Testing Endpoints

Using curl:

# Test health
curl http://localhost:8000/health

# Test with formatting
curl http://localhost:8000/api/providers | python -m json.tool

Using Python:

import requests

# Get health status
response = requests.get('http://localhost:8000/health')
print(response.json())

# Get crypto prices
response = requests.get('http://localhost:8000/api/crypto/prices/top')
prices = response.json()
for crypto in prices:
    print(f"{crypto['symbol']}: ${crypto['price']}")

Using JavaScript:

// Fetch crypto prices
fetch('http://localhost:8000/api/crypto/prices/top')
  .then(response => response.json())
  .then(data => console.log(data));

// WebSocket connection
const ws = new WebSocket('ws://localhost:8000/ws/live');
ws.onmessage = (event) => {
  console.log('Update:', JSON.parse(event.data));
};

---

📞 Support

برای سوالات بیشتر، به README.md مراجعه کنید.

For more questions, refer to README.md.