Environment Variables

You can also configure ApiMonitor using environment variables:

export APIMONITOR_URL="https://api.example.com/health"
export APIMONITOR_INTERVAL=300
export APIMONITOR_TIMEOUT=10
export APIMONITOR_SLACK_WEBHOOK="https://hooks.slack.com/services/..."
export APIMONITOR_LOG_LEVEL="INFO"
export APIMONITOR_DASHBOARD=true

apimonitor run

🔧 Advanced Usage

Custom Health Checks

from apimonitor import ApiMonitor
from apimonitor.models import EndpointConfig, HttpMethod

# Advanced endpoint configuration
endpoint = EndpointConfig(
    id="api_advanced",
    url="https://api.example.com/data",
    method=HttpMethod.POST,
    headers={"Authorization": "Bearer token", "Content-Type": "application/json"},
    body='{"query": "test"}',
    expected_status_codes=[200, 201],
    expected_response_time_ms=500,
    response_contains="success",
    response_not_contains="error",
    check_interval_seconds=120,
    max_retries=3,
    sla_uptime_percentage=99.9,
    sla_response_time_ms=1000
)

monitor = ApiMonitor()
monitor.config.add_endpoint(endpoint)

Custom Notifications

# Webhook notification
monitor.add_notification_channel("webhook", "webhook", {
    "url": "https://your-webhook.com/alerts",
    "headers": {"Authorization": "Bearer webhook-token"}
})

# Discord notification
monitor.add_notification_channel("discord", "discord", {
    "webhook_url": "https://discord.com/api/webhooks/YOUR_WEBHOOK"
})

# Email notification
monitor.add_notification_channel("email", "email", {
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "username": "alerts@yourcompany.com",
    "password": "your-password",
    "from_email": "alerts@yourcompany.com",
    "to_emails": ["admin@yourcompany.com"]
})

Monitoring with Context Manager

async with ApiMonitor() as monitor:
    monitor.add_endpoint("https://api.example.com/health", "api_health")
    
    # Check once
    result = await monitor.check_endpoint("api_health")
    print(f"Health: {result.health_status}")
    
    # Get statistics
    stats = monitor.get_endpoint_stats("api_health")
    print(f"Uptime: {stats.uptime_percentage:.2f}%")

📊 Dashboard

ApiMonitor includes an optional web dashboard for real-time monitoring:

# Install dashboard dependencies
pip install apimonitor[dashboard]

# Start with dashboard
apimonitor run --config-file config.yaml --dashboard --dashboard-port 8080

Visit http://localhost:8080 to see:

• Real-time endpoint status
• Response time graphs
• Uptime statistics
• Recent alerts and events
• SLA compliance tracking

🐳 Docker Deployment

Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY config.yaml .
COPY . .

CMD ["apimonitor", "run", "--config-file", "config.yaml"]

Docker Compose

version: '3.8'
services:
  apimonitor:
    build: .
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./logs:/app/logs
    ports:
      - "8080:8080"
    environment:
      - APIMONITOR_LOG_LEVEL=INFO
    restart: unless-stopped

📚 CLI Reference

Commands

• apimonitor run - Start continuous monitoring
• apimonitor check - Check endpoints once
• apimonitor init - Create example configuration
• apimonitor validate - Validate configuration file
• apimonitor stats - Show monitoring statistics

Global Options

• --config, -c - Configuration file path
• --verbose, -v - Verbose output
• --version - Show version

Run Command Options

• --config-file, -c - Configuration file
• --interval, -i - Check interval in seconds
• --timeout, -t - Request timeout in seconds
• --slack-webhook - Slack webhook URL
• --discord-webhook - Discord webhook URL
• --email-config - Email configuration (JSON)
• --dashboard - Enable web dashboard
• --dashboard-port - Dashboard port
• --background, -b - Run in background

Check Command Options

• --timeout, -t - Request timeout in seconds
• --method, -m - HTTP method
• --headers, -H - HTTP headers (key:value)
• --expected-status - Expected status codes
• --json-output, -j - Output as JSON
• --quiet, -q - Quiet mode

🧪 Testing

# Install test dependencies
pip install apimonitor[dev]

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=apimonitor --cov-report=html

🔄 Integration Examples

CI/CD Pipeline Health Check

# GitHub Actions example
- name: Check API Health
  run: |
    pip install apimonitor
    apimonitor check https://api.staging.example.com/health --expected-status 200

Kubernetes Health Check

apiVersion: batch/v1
kind: CronJob
metadata:
  name: api-health-check
spec:
  schedule: "*/5 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: apimonitor
            image: your-registry/apimonitor:latest
            command: ["apimonitor", "check", "https://api.example.com/health"]
          restartPolicy: OnFailure

Serverless Monitoring (AWS Lambda)

import json
import asyncio
from apimonitor import quick_check

def lambda_handler(event, context):
    async def check_apis():
        urls = ["https://api1.example.com/health", "https://api2.example.com/health"]
        results = []
        
        for url in urls:
            result = await quick_check(url)
            results.append({
                "url": url,
                "status": result.health_status.value,
                "response_time": result.response_time_ms,
                "success": result.success
            })
        
        return results
    
    results = asyncio.run(check_apis())
    
    return {
        'statusCode': 200,
        'body': json.dumps(results)
    }

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/abderrahimghazali/apimonitor.git
cd apimonitor

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black apimonitor/ tests/
isort apimonitor/ tests/

# Lint code
flake8 apimonitor/ tests/

🐛 Troubleshooting

Common Issues

1. SSL Certificate Errors

# Disable SSL verification (not recommended for production)
endpoint_config = EndpointConfig(
    id="test",
    url="https://self-signed-cert-site.com",
    # Add custom session configuration in future versions
)

2. Timeout Issues

endpoints:
  - id: "slow_api"
    url: "https://slow-api.example.com"
    timeout_seconds: 30  # Increase timeout
    max_retries: 5       # Increase retries

3. Rate Limiting

endpoints:
  - id: "rate_limited_api"
    url: "https://api.example.com"
    check_interval_seconds: 600  # Check less frequently

4. Memory Usage

# Limit history retention
max_history_days: 7

🙏 Acknowledgments

• Built with aiohttp for fast async HTTP requests
• Uses pydantic for configuration validation
• CLI powered by click
• Dashboard built with FastAPI (optional)

Need help?

• 🐛 Report Issues
• 💬 Discussions

Example Configuration Files

config/basic.yaml

log_level: "INFO"
dashboard_enabled: false

endpoints:
  - id: "google"
    url: "https://www.google.com"
    check_interval_seconds: 300
    timeout_seconds: 10
    expected_status_codes: [200]

notifications:
  console:
    type: "console"
    enabled: true
    on_failure: true
    on_recovery: true

config/advanced.yaml

log_level: "INFO"
log_file: "logs/apimonitor.log"
max_history_days: 30
dashboard_enabled: true
dashboard_port: 8080

# Default settings for all endpoints
default_timeout: 10.0
default_interval: 300
default_retries: 3

endpoints:
  - id: "api_health"
    url: "https://api.example.com/health"
    method: "GET"
    check_interval_seconds: 60
    timeout_seconds: 5
    expected_status_codes: [200]
    expected_response_time_ms: 500
    headers:
      User-Agent: "ApiMonitor/1.0"
      Authorization: "Bearer token123"
    sla_uptime_percentage: 99.9
    sla_response_time_ms: 1000

  - id: "api_users_post"
    url: "https://api.example.com/users"
    method: "POS