wtrinkl/laravel-llm-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
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

1167 lines
26 KiB
Markdown
Raw Permalink 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"provider": "openai",
"api_key": "sk-proj-abc123...",
"organization_id": null,
"test_connection": true
}
```
**Response:**
```json
{
"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:**
```json
{
"api_key": "sk-proj-new-key-...",
"organization_id": "org-123",
"is_active": true,
"test_connection": true
}
```
---
#### `DELETE /api/credentials/{id}`
Credentials löschen.
**Response:**
```json
{
"message": "Credentials successfully deleted"
}
```
---
#### `POST /api/credentials/{id}/test`
Credentials testen ohne zu ändern.
**Response:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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`:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:
```json
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key",
"status": 401
}
}
```
---
## 📝 Standard-Response-Formate
### Success Response
```json
{
"data": { /* Resource data */ },
"meta": { /* Optional metadata */ }
}
```
### Error Response
```json
{
"error": {
"code": "error_code",
"message": "Human-readable error message",
"status": 400,
"details": { /* Optional additional details */ }
}
}
```
### Pagination
```json
{
"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)
5. Credentials-Management (`/api/credentials/*`)
6. Budget-Endpoints (`/api/budget`, `/api/budget/history`)
7. Pricing-Endpoints (`/api/pricing`, `/api/pricing/calculator`)
### Phase 3: Analytics (Prio: MITTEL)
8. Usage-Summary (`/api/usage/summary`)
9. Request-History (`/api/usage/requests`)
10. Chart-Data (`/api/usage/charts`)
### Phase 4: Account (Prio: NIEDRIG)
11. Account-Info (`/api/account`)
12. 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