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:**
```bash
curl http://localhost:8000/health
```

**Response:**
```json
{
  "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:**
```bash
curl http://localhost:8000/info
```

**Response:**
```json
{
  "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:**
```bash
curl http://localhost:8000/api/providers
```

**Response:**
```json
[
  {
    "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:**
```bash
curl http://localhost:8000/api/crypto/prices/top?limit=5
```

**Response:**
```json
[
  {
    "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:**
```bash
curl http://localhost:8000/api/crypto/market-overview
```

**Response:**
```json
{
  "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:**
```bash
curl http://localhost:8000/api/categories
```

**Response:**
```json
[
  {
    "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:**
```bash
curl http://localhost:8000/api/rate-limits
```

**Response:**
```json
[
  {
    "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:**
```bash
curl http://localhost:8000/api/logs?limit=10
```

**Response:**
```json
[
  {
    "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:**
```bash
curl http://localhost:8000/api/alerts
```

**Response:**
```json
[
  {
    "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:**
```bash
curl http://localhost:8000/api/hf/health
```

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

---

### POST /api/hf/refresh
Refresh Hugging Face data

**Request:**
```bash
curl -X POST http://localhost:8000/api/hf/refresh
```

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

---

### GET /api/hf/registry
Get Hugging Face model registry

**Request:**
```bash
curl http://localhost:8000/api/hf/registry
```

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

---

### POST /api/hf/run-sentiment
Run sentiment analysis

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

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

---

## 🔌 WebSocket

### WS /ws/live
Real-time updates via WebSocket

**Connection:**
```javascript
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
```json
{
  "type": "connection_established",
  "timestamp": "2025-01-15T10:30:00"
}
```

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

#### Provider Status Change
```json
{
  "type": "provider_status_change",
  "data": {
    "provider": "Binance",
    "status": "operational"
  },
  "timestamp": "2025-01-15T10:30:00"
}
```

#### New Alert
```json
{
  "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:
```bash
# Test health
curl http://localhost:8000/health

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

### Using Python:
```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:
```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`.