wtrinkl/laravel-llm-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c65643ac1f912a658eac5e38822b7a3d6455df90
laravel-llm-gateway/API_KONZEPT.md
wtrinkl b6d75d51e3 feat: Implementiere umfassende RESTful API für LLM Gateway 
Fügt 21 neue API-Endpoints in 4 Phasen hinzu:

Phase 1 - Foundation (Provider & Models):
- GET /api/providers - Liste aller Provider
- GET /api/providers/{provider} - Provider-Details
- GET /api/models - Liste aller Models mit Filtering/Sorting
- GET /api/models/{provider}/{model} - Model-Details

Phase 2 - Core Features (Credentials, Budget, Pricing):
- GET/POST/PUT/DELETE /api/credentials - Credential-Management
- POST /api/credentials/{id}/test - Connection Testing
- GET /api/budget - Budget-Status mit Projektionen
- GET /api/budget/history - Budget-Historie
- GET /api/pricing - Model-Pricing-Listen
- GET /api/pricing/calculator - Kosten-Kalkulator
- GET /api/pricing/compare - Preis-Vergleich

Phase 3 - Analytics (Usage Statistics):
- GET /api/usage/summary - Umfassende Statistiken
- GET /api/usage/requests - Request-History mit Pagination
- GET /api/usage/requests/{id} - Request-Details
- GET /api/usage/charts - Chart-Daten (4 Typen)

Phase 4 - Account (Account Info & Activity):
- GET /api/account - User-Informationen
- GET /api/account/activity - Activity-Log

Features:
- Vollständige Scramble/Swagger-Dokumentation
- Consistent Error-Handling
- API-Key Authentication
- Filtering, Sorting, Pagination
- Budget-Tracking mit Alerts
- Provider-Breakdown
- Performance-Metriken
- Chart-Ready-Data

Controller erstellt:
- ProviderController
- ModelController
- CredentialController
- BudgetController
- PricingController
- UsageController
- AccountController

Dokumentation:
- API_KONZEPT.md - Vollständiges API-Konzept
- API_IMPLEMENTATION_STATUS.txt - Implementation-Tracking
- API_IMPLEMENTATION_SUMMARY.md - Zusammenfassung und Workflows
2025-11-19 12:33:11 +01:00

26 KiB
Raw Blame History

API-Konzept für Laravel LLM Gateway

Version: 1.0
Datum: 2025-11-19
Status: 📋 Konzept

🎯 Zielsetzung

Entwicklung einer modernen, RESTful API für das Laravel LLM Gateway mit folgenden Hauptzielen:

  • Self-Service: Gateway-User können alle relevanten Informationen selbst abfragen
  • Transparenz: Vollständige Einsicht in Verbrauch, Kosten und Budget
  • Provider-Agnostisch: Einheitliche Schnittstelle für alle LLM-Provider
  • OpenAPI-Dokumentation: Vollständige Swagger/Scramble-Dokumentation

📊 Aktuelle Situation

✅ Was funktioniert:

  • Chat Completions Endpoint (/api/chat/completions)
  • API-Key Authentication
  • Basis-User-Info Endpoint

❌ Was fehlt:

  • Provider-Discovery (Welche Provider sind verfügbar?)
  • Model-Discovery (Welche Modelle gibt es pro Provider?)
  • Budget-Management Endpoints
  • Usage-Statistics Endpoints
  • Pricing-Information Endpoints
  • Credentials-Management für Gateway-User
  • Rate-Limit-Informationen

🏗️ Vorgeschlagene API-Struktur

Übersicht der Endpoint-Kategorien

/api
├── /providers              # Provider-Discovery
├── /models                 # Model-Discovery
├── /credentials            # Eigene Credentials verwalten
├── /chat                   # LLM-Interaktion
├── /budget                 # Budget-Management
├── /usage                  # Usage-Statistics
├── /pricing                # Model-Pricing
└── /account                # Account-Informationen

📋 Detaillierte API-Spezifikation

1. Provider-Management

GET /api/providers

Liste aller unterstützten LLM-Provider.

Response:

{
  "data": [
    {
      "id": "openai",
      "name": "OpenAI",
      "status": "available",
      "has_credentials": true,
      "credentials_status": "active",
      "last_tested": "2025-11-19T10:30:00Z",
      "supported_features": ["chat", "streaming"],
      "models_count": 12
    },
    {
      "id": "anthropic",
      "name": "Anthropic",
      "status": "available",
      "has_credentials": true,
      "credentials_status": "active",
      "last_tested": "2025-11-19T10:25:00Z",
      "supported_features": ["chat", "streaming"],
      "models_count": 8
    },
    {
      "id": "gemini",
      "name": "Google Gemini",
      "status": "available",
      "has_credentials": false,
      "credentials_status": null,
      "last_tested": null,
      "supported_features": ["chat"],
      "models_count": 6
    }
  ]
}

Use Cases:

  • Dashboard: Provider-Status anzeigen
  • Setup: Welche Provider kann ich nutzen?
  • Integration: Welche Features unterstützt ein Provider?

GET /api/providers/{provider}

Details zu einem spezifischen Provider.

Response:

{
  "data": {
    "id": "openai",
    "name": "OpenAI",
    "description": "OpenAI GPT Models",
    "status": "available",
    "has_credentials": true,
    "credentials_status": "active",
    "credentials": {
      "api_key_format": "sk-...",
      "organization_id_required": false,
      "last_tested": "2025-11-19T10:30:00Z",
      "test_status": "success"
    },
    "supported_features": ["chat", "streaming", "function_calling"],
    "api_documentation": "https://platform.openai.com/docs/api-reference",
    "models": [
      {
        "id": "gpt-4-turbo",
        "name": "GPT-4 Turbo",
        "context_window": 128000,
        "max_output_tokens": 4096,
        "supports_streaming": true,
        "supports_function_calling": true,
        "pricing": {
          "input_per_1k": 0.01,
          "output_per_1k": 0.03,
          "currency": "USD"
        }
      }
    ],
    "rate_limits": {
      "requests_per_minute": 10000,
      "tokens_per_minute": 2000000
    },
    "statistics": {
      "total_requests": 1250,
      "total_cost": 45.67,
      "total_tokens": 2500000,
      "last_used": "2025-11-19T11:45:00Z"
    }
  }
}

2. Model-Discovery

GET /api/models

Liste aller verfügbaren Modelle über alle Provider hinweg.

Query Parameters:

  • provider (optional): Filter nach Provider
  • supports_streaming (optional): Nur Streaming-fähige Modelle
  • max_price (optional): Maximaler Preis pro 1k Tokens
  • min_context (optional): Minimale Context Window Size
  • sort (optional): price, context, popularity

Response:

{
  "data": [
    {
      "id": "gpt-4-turbo",
      "provider": "openai",
      "provider_name": "OpenAI",
      "name": "GPT-4 Turbo",
      "description": "Most capable GPT-4 model",
      "context_window": 128000,
      "max_output_tokens": 4096,
      "supports_streaming": true,
      "supports_function_calling": true,
      "supports_vision": true,
      "pricing": {
        "input_per_1k_tokens": 0.01,
        "output_per_1k_tokens": 0.03,
        "currency": "USD"
      },
      "availability": "available"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "provider": "anthropic",
      "provider_name": "Anthropic",
      "name": "Claude 3.5 Sonnet",
      "description": "Most intelligent Claude model",
      "context_window": 200000,
      "max_output_tokens": 8192,
      "supports_streaming": true,
      "supports_function_calling": true,
      "supports_vision": true,
      "pricing": {
        "input_per_1k_tokens": 0.003,
        "output_per_1k_tokens": 0.015,
        "currency": "USD"
      },
      "availability": "available"
    }
  ],
  "meta": {
    "total": 42,
    "filtered": 2,
    "providers_count": 5
  }
}

Use Cases:

  • Model-Selection: Bestes Modell für Use Case finden
  • Price-Comparison: Günstigste Option ermitteln
  • Feature-Check: Welche Modelle unterstützen Vision/Functions?

GET /api/models/{provider}/{model}

Detaillierte Informationen zu einem spezifischen Modell.

Response:

{
  "data": {
    "id": "gpt-4-turbo",
    "provider": "openai",
    "provider_name": "OpenAI",
    "name": "GPT-4 Turbo",
    "full_name": "OpenAI GPT-4 Turbo",
    "description": "Most capable GPT-4 model with improved instruction following",
    "release_date": "2024-04-09",
    "deprecation_date": null,
    "status": "active",
    "capabilities": {
      "context_window": 128000,
      "max_output_tokens": 4096,
      "supports_streaming": true,
      "supports_function_calling": true,
      "supports_vision": true,
      "supports_json_mode": true,
      "training_data_cutoff": "2023-12"
    },
    "pricing": {
      "input_per_1k_tokens": 0.01,
      "output_per_1k_tokens": 0.03,
      "currency": "USD",
      "last_updated": "2024-11-01T00:00:00Z"
    },
    "performance": {
      "avg_response_time_ms": 1250,
      "p95_response_time_ms": 2800,
      "success_rate": 99.8
    },
    "your_usage": {
      "total_requests": 145,
      "total_tokens": 250000,
      "total_cost": 3.75,
      "avg_tokens_per_request": 1724,
      "last_used": "2025-11-19T11:30:00Z"
    },
    "documentation": "https://platform.openai.com/docs/models/gpt-4-turbo",
    "best_for": ["complex reasoning", "code generation", "analysis"]
  }
}

3. Credentials-Management

GET /api/credentials

Liste aller eigenen Provider-Credentials.

Response:

{
  "data": [
    {
      "id": 1,
      "provider": "openai",
      "provider_name": "OpenAI",
      "api_key_preview": "sk-proj-...xyz",
      "organization_id": null,
      "is_active": true,
      "status": "verified",
      "last_used": "2025-11-19T11:45:00Z",
      "last_tested": "2025-11-19T10:30:00Z",
      "test_result": {
        "status": "success",
        "message": "Connection successful",
        "tested_at": "2025-11-19T10:30:00Z"
      },
      "created_at": "2025-11-10T08:00:00Z",
      "updated_at": "2025-11-19T10:30:00Z"
    },
    {
      "id": 2,
      "provider": "anthropic",
      "provider_name": "Anthropic",
      "api_key_preview": "sk-ant-...abc",
      "organization_id": null,
      "is_active": true,
      "status": "verified",
      "last_used": "2025-11-19T11:30:00Z",
      "last_tested": "2025-11-19T10:25:00Z",
      "test_result": {
        "status": "success",
        "message": "Connection successful",
        "tested_at": "2025-11-19T10:25:00Z"
      },
      "created_at": "2025-11-12T09:00:00Z",
      "updated_at": "2025-11-19T10:25:00Z"
    }
  ]
}

POST /api/credentials

Neue Credentials für einen Provider hinzufügen.

Request:

{
  "provider": "openai",
  "api_key": "sk-proj-abc123...",
  "organization_id": null,
  "test_connection": true
}

Response:

{
  "data": {
    "id": 3,
    "provider": "openai",
    "provider_name": "OpenAI",
    "api_key_preview": "sk-proj-...xyz",
    "organization_id": null,
    "is_active": true,
    "status": "verified",
    "test_result": {
      "status": "success",
      "message": "Connection successful",
      "model_tested": "gpt-3.5-turbo"
    },
    "created_at": "2025-11-19T12:00:00Z"
  },
  "message": "Credentials successfully added and verified"
}

PUT /api/credentials/{id}

Bestehende Credentials aktualisieren.

Request:

{
  "api_key": "sk-proj-new-key-...",
  "organization_id": "org-123",
  "is_active": true,
  "test_connection": true
}

DELETE /api/credentials/{id}

Credentials löschen.

Response:

{
  "message": "Credentials successfully deleted"
}

POST /api/credentials/{id}/test

Credentials testen ohne zu ändern.

Response:

{
  "status": "success",
  "message": "Connection successful",
  "details": {
    "provider": "openai",
    "model_tested": "gpt-3.5-turbo",
    "response_time_ms": 245,
    "tested_at": "2025-11-19T12:05:00Z"
  }
}

4. Chat Completions (Erweitert)

POST /api/chat/completions

LLM Chat Completion Request (OpenAI-kompatibel).

Request:

{
  "model": "gpt-4-turbo",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 500,
  "stream": false
}

Response:

{
  "id": "req_abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4-turbo",
  "provider": "openai",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 8,
    "total_tokens": 23
  },
  "cost": {
    "input_cost": 0.00015,
    "output_cost": 0.00024,
    "total_cost": 0.00039,
    "currency": "USD"
  },
  "metadata": {
    "gateway_request_id": "req_abc123",
    "response_time_ms": 1245,
    "budget_remaining": 98.75
  }
}

5. Budget-Management

GET /api/budget

Aktuelles Budget und Limits abrufen.

Response:

{
  "data": {
    "total_budget": 100.00,
    "used_budget": 45.67,
    "remaining_budget": 54.33,
    "budget_percentage": 45.67,
    "currency": "USD",
    "period": "monthly",
    "period_start": "2025-11-01T00:00:00Z",
    "period_end": "2025-11-30T23:59:59Z",
    "days_remaining": 11,
    "projected_spend": 95.34,
    "projected_overspend": false,
    "limits": {
      "daily_limit": 10.00,
      "daily_used": 2.45,
      "daily_remaining": 7.55,
      "request_limit_per_minute": 100,
      "token_limit_per_request": 10000
    },
    "alerts": {
      "threshold_50_percent": false,
      "threshold_75_percent": false,
      "threshold_90_percent": false,
      "approaching_daily_limit": false
    },
    "breakdown_by_provider": [
      {
        "provider": "openai",
        "provider_name": "OpenAI",
        "spent": 25.30,
        "percentage": 55.4,
        "requests": 850
      },
      {
        "provider": "anthropic",
        "provider_name": "Anthropic",
        "spent": 20.37,
        "percentage": 44.6,
        "requests": 400
      }
    ],
    "updated_at": "2025-11-19T12:00:00Z"
  }
}

Use Cases:

  • Dashboard: Budget-Status anzeigen
  • Alerts: Warnung bei Budget-Überschreitung
  • Planning: Hochrechnung für Monatsende

GET /api/budget/history

Budget-Verlauf über die Zeit.

Query Parameters:

  • period (optional): daily, weekly, monthly (default: daily)
  • days (optional): Anzahl Tage zurück (default: 30)

Response:

{
  "data": [
    {
      "date": "2025-11-19",
      "total_cost": 2.45,
      "total_requests": 45,
      "total_tokens": 45000,
      "breakdown": [
        {
          "provider": "openai",
          "cost": 1.35,
          "requests": 25
        },
        {
          "provider": "anthropic",
          "cost": 1.10,
          "requests": 20
        }
      ]
    },
    {
      "date": "2025-11-18",
      "total_cost": 3.67,
      "total_requests": 68,
      "total_tokens": 78000,
      "breakdown": [
        {
          "provider": "openai",
          "cost": 2.10,
          "requests": 40
        },
        {
          "provider": "anthropic",
          "cost": 1.57,
          "requests": 28
        }
      ]
    }
  ],
  "meta": {
    "period": "daily",
    "days": 30,
    "total_cost": 45.67,
    "total_requests": 1250,
    "avg_daily_cost": 1.52,
    "avg_daily_requests": 41.7
  }
}

6. Usage Statistics

GET /api/usage/summary

Zusammenfassung der Nutzungsstatistiken.

Query Parameters:

  • period (optional): today, week, month, all (default: month)
  • provider (optional): Filter nach Provider

Response:

{
  "data": {
    "period": "month",
    "period_start": "2025-11-01T00:00:00Z",
    "period_end": "2025-11-30T23:59:59Z",
    "summary": {
      "total_requests": 1250,
      "successful_requests": 1235,
      "failed_requests": 15,
      "success_rate": 98.8,
      "total_tokens": 2500000,
      "prompt_tokens": 1800000,
      "completion_tokens": 700000,
      "total_cost": 45.67,
      "avg_cost_per_request": 0.0365,
      "avg_tokens_per_request": 2000,
      "avg_response_time_ms": 1450
    },
    "by_provider": [
      {
        "provider": "openai",
        "provider_name": "OpenAI",
        "requests": 850,
        "tokens": 1700000,
        "cost": 25.30,
        "avg_response_time_ms": 1350,
        "success_rate": 99.2
      },
      {
        "provider": "anthropic",
        "provider_name": "Anthropic",
        "requests": 400,
        "tokens": 800000,
        "cost": 20.37,
        "avg_response_time_ms": 1650,
        "success_rate": 98.0
      }
    ],
    "by_model": [
      {
        "model": "gpt-4-turbo",
        "provider": "openai",
        "requests": 450,
        "tokens": 900000,
        "cost": 15.50,
        "avg_tokens_per_request": 2000
      },
      {
        "model": "claude-3-5-sonnet-20241022",
        "provider": "anthropic",
        "requests": 400,
        "tokens": 800000,
        "cost": 20.37,
        "avg_tokens_per_request": 2000
      }
    ],
    "top_hours": [
      {
        "hour": 14,
        "requests": 150,
        "cost": 5.45
      },
      {
        "hour": 10,
        "requests": 140,
        "cost": 5.10
      }
    ]
  }
}

GET /api/usage/requests

Liste der einzelnen Requests mit Details.

Query Parameters:

  • page (optional): Seite (default: 1)
  • per_page (optional): Items pro Seite (default: 20, max: 100)
  • provider (optional): Filter nach Provider
  • model (optional): Filter nach Model
  • status (optional): success, failed, all (default: all)
  • date_from (optional): Von Datum (ISO 8601)
  • date_to (optional): Bis Datum (ISO 8601)
  • sort (optional): created_at, cost, tokens, response_time (default: -created_at)

Response:

{
  "data": [
    {
      "id": "req_abc123",
      "provider": "openai",
      "model": "gpt-4-turbo",
      "status": "success",
      "prompt_tokens": 150,
      "completion_tokens": 85,
      "total_tokens": 235,
      "input_cost": 0.0015,
      "output_cost": 0.00255,
      "total_cost": 0.00405,
      "response_time_ms": 1245,
      "created_at": "2025-11-19T11:45:00Z",
      "metadata": {
        "has_streaming": false,
        "has_function_calling": false,
        "temperature": 0.7
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1250,
    "total_pages": 63,
    "has_more": true
  },
  "summary": {
    "total_cost": 45.67,
    "total_tokens": 2500000,
    "avg_response_time_ms": 1450
  }
}

GET /api/usage/requests/{id}

Details zu einem spezifischen Request.

Response:

{
  "data": {
    "id": "req_abc123",
    "gateway_user_id": "usr_xyz",
    "provider": "openai",
    "provider_name": "OpenAI",
    "model": "gpt-4-turbo",
    "status": "success",
    "request": {
      "messages": [
        {
          "role": "user",
          "content": "What is the capital of France?"
        }
      ],
      "temperature": 0.7,
      "max_tokens": 500
    },
    "response": {
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    },
    "usage": {
      "prompt_tokens": 15,
      "completion_tokens": 8,
      "total_tokens": 23
    },
    "cost": {
      "input_cost": 0.00015,
      "output_cost": 0.00024,
      "total_cost": 0.00039,
      "currency": "USD",
      "pricing_at_request": {
        "input_per_1k": 0.01,
        "output_per_1k": 0.03
      }
    },
    "performance": {
      "response_time_ms": 1245,
      "time_to_first_token_ms": 450
    },
    "metadata": {
      "ip_address": "192.168.1.1",
      "user_agent": "MyApp/1.0",
      "stream": false,
      "has_function_calling": false
    },
    "created_at": "2025-11-19T11:45:00Z",
    "completed_at": "2025-11-19T11:45:01Z"
  }
}

GET /api/usage/charts

Chart-Daten für Visualisierungen.

Query Parameters:

  • type: daily_cost, provider_distribution, model_usage, hourly_pattern
  • days (optional): Anzahl Tage zurück (default: 30)

Response für type=daily_cost:

{
  "data": {
    "type": "daily_cost",
    "labels": [
      "2025-11-01",
      "2025-11-02",
      "..."
    ],
    "datasets": [
      {
        "label": "Daily Cost",
        "data": [1.45, 2.30, 1.85, "..."],
        "backgroundColor": "rgba(59, 130, 246, 0.5)",
        "borderColor": "rgba(59, 130, 246, 1)"
      },
      {
        "label": "7-day Moving Average",
        "data": [1.50, 1.87, 1.98, "..."],
        "borderColor": "rgba(239, 68, 68, 1)",
        "type": "line"
      }
    ]
  }
}

7. Model Pricing

GET /api/pricing

Aktuelle Preise für alle Modelle.

Query Parameters:

  • provider (optional): Filter nach Provider
  • sort (optional): price, name, provider

Response:

{
  "data": [
    {
      "provider": "openai",
      "provider_name": "OpenAI",
      "model": "gpt-4-turbo",
      "model_name": "GPT-4 Turbo",
      "pricing": {
        "input_per_1k_tokens": 0.01,
        "output_per_1k_tokens": 0.03,
        "currency": "USD"
      },
      "last_updated": "2024-11-01T00:00:00Z"
    },
    {
      "provider": "anthropic",
      "provider_name": "Anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "model_name": "Claude 3.5 Sonnet",
      "pricing": {
        "input_per_1k_tokens": 0.003,
        "output_per_1k_tokens": 0.015,
        "currency": "USD"
      },
      "last_updated": "2024-10-22T00:00:00Z"
    }
  ],
  "meta": {
    "total_models": 42,
    "providers_count": 5,
    "last_sync": "2025-11-19T10:00:00Z"
  }
}

GET /api/pricing/calculator

Kosten-Kalkulator für hypothetische Requests.

Query Parameters:

  • model: Model-ID
  • input_tokens: Anzahl Input-Tokens
  • output_tokens: Anzahl Output-Tokens

Response:

{
  "data": {
    "model": "gpt-4-turbo",
    "provider": "openai",
    "input_tokens": 1000,
    "output_tokens": 500,
    "pricing": {
      "input_per_1k": 0.01,
      "output_per_1k": 0.03,
      "currency": "USD"
    },
    "calculation": {
      "input_cost": 0.01,
      "output_cost": 0.015,
      "total_cost": 0.025,
      "currency": "USD"
    },
    "examples": {
      "10_requests": 0.25,
      "100_requests": 2.50,
      "1000_requests": 25.00
    }
  }
}

8. Account-Information

GET /api/account

Informationen zum eigenen Gateway-User Account.

Response:

{
  "data": {
    "user_id": "usr_xyz789",
    "name": "API Client App",
    "email": "api@example.com",
    "status": "active",
    "created_at": "2025-11-01T08:00:00Z",
    "last_login": "2025-11-19T11:45:00Z",
    "api_keys": [
      {
        "id": "key_123",
        "name": "Production Key",
        "key_preview": "gw_...xyz",
        "created_at": "2025-11-01T08:00:00Z",
        "last_used": "2025-11-19T11:45:00Z",
        "expires_at": null
      }
    ],
    "providers_configured": 3,
    "budget": {
      "total": 100.00,
      "used": 45.67,
      "remaining": 54.33,
      "currency": "USD"
    },
    "statistics": {
      "total_requests": 1250,
      "total_tokens": 2500000,
      "total_cost": 45.67,
      "first_request": "2025-11-05T10:00:00Z"
    },
    "rate_limits": {
      "requests_per_minute": 100,
      "tokens_per_request": 10000,
      "daily_budget_limit": 10.00
    }
  }
}

GET /api/account/activity

Recent Activity Log.

Query Parameters:

  • limit (optional): Anzahl Items (default: 20, max: 100)
  • type (optional): request, credential_change, budget_alert, all (default: all)

Response:

{
  "data": [
    {
      "id": 1,
      "type": "request",
      "action": "chat_completion",
      "details": {
        "provider": "openai",
        "model": "gpt-4-turbo",
        "cost": 0.00405,
        "status": "success"
      },
      "timestamp": "2025-11-19T11:45:00Z"
    },
    {
      "id": 2,
      "type": "credential_change",
      "action": "credentials_added",
      "details": {
        "provider": "anthropic"
      },
      "timestamp": "2025-11-12T09:00:00Z"
    },
    {
      "id": 3,
      "type": "budget_alert",
      "action": "75_percent_reached",
      "details": {
        "budget_used": 75.00,
        "budget_total": 100.00
      },
      "timestamp": "2025-11-18T14:30:00Z"
    }
  ],
  "meta": {
    "total": 156,
    "limit": 20,
    "has_more": true
  }
}

🔐 Authentifizierung & Authorization

API-Key Authentication

Alle API-Endpoints erfordern einen gültigen API-Key im Header:

Authorization: Bearer gw_abc123xyz789...

Response bei fehlender/ungültiger Authentifizierung:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

📝 Standard-Response-Formate

Success Response

{
  "data": { /* Resource data */ },
  "meta": { /* Optional metadata */ }
}

Error Response

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "status": 400,
    "details": { /* Optional additional details */ }
  }
}

Pagination

{
  "data": [ /* Array of items */ ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1250,
    "total_pages": 63,
    "has_more": true
  },
  "links": {
    "first": "/api/endpoint?page=1",
    "last": "/api/endpoint?page=63",
    "prev": null,
    "next": "/api/endpoint?page=2"
  }
}

⚠️ Error-Codes

Code HTTP Status Beschreibung
unauthorized 401 Fehlende oder ungültige Authentifizierung
forbidden 403 Zugriff verweigert
not_found 404 Resource nicht gefunden
validation_error 422 Validierungsfehler in Request-Daten
rate_limit_exceeded 429 Rate-Limit überschritten
budget_exceeded 402 Budget aufgebraucht
provider_error 502 Fehler beim LLM-Provider
provider_unavailable 503 Provider nicht erreichbar
internal_error 500 Interner Server-Fehler

🚀 Implementierungsreihenfolge

Phase 1: Foundation (Prio: HOCH)

  1. ✅ Basis API-Struktur mit Scramble
  2. ✅ Error-Handling & Response-Formate
  3. Provider-Endpoints (/api/providers, /api/providers/{id})
  4. Model-Endpoints (/api/models, /api/models/{provider}/{model})

Phase 2: Core-Features (Prio: HOCH)

  1. Credentials-Management (/api/credentials/*)
  2. Budget-Endpoints (/api/budget, /api/budget/history)
  3. Pricing-Endpoints (/api/pricing, /api/pricing/calculator)

Phase 3: Analytics (Prio: MITTEL)

  1. Usage-Summary (/api/usage/summary)
  2. Request-History (/api/usage/requests)
  3. Chart-Data (/api/usage/charts)

Phase 4: Account (Prio: NIEDRIG)

  1. Account-Info (/api/account)
  2. Activity-Log (/api/account/activity)

📊 Vorteile der neuen API-Struktur

Für Gateway-User:

  • ✅ Self-Service: Alle Informationen selbst abrufbar
  • ✅ Transparenz: Vollständiger Überblick über Kosten und Verbrauch
  • ✅ Flexibilität: Provider und Modelle frei wählbar
  • ✅ Kontrolle: Budget-Management in eigener Hand

Für Entwickler:

  • ✅ RESTful: Standard-konforme API-Struktur
  • ✅ Dokumentiert: Vollständige Swagger/Scramble-Docs
  • ✅ Konsistent: Einheitliche Response-Formate
  • ✅ Skalierbar: Einfach erweiterbar

Für das System:

  • ✅ Modular: Klare Trennung der Verantwortlichkeiten
  • ✅ Wartbar: Übersichtliche Controller-Struktur
  • ✅ Testbar: Alle Endpoints einzeln testbar
  • ✅ Erweiterbar: Neue Provider/Features einfach integrierbar

🎯 Nächste Schritte

  1. Review: Konzept durchgehen und finalisieren
  2. Implementation: Controller und Routes implementieren
  3. Testing: Comprehensive API-Tests schreiben
  4. Documentation: Scramble-Annotations hinzufügen
  5. Deployment: API live schalten

Feedback erwünscht! 💬

Reference in New Issue View Git Blame Copy Permalink