motia/bitbylaw/steps/advoware_proxy/README.md

# Advoware API Proxy Steps

Dieser Ordner enthält die API-Proxy-Steps für die Advoware-Integration. Jeder Step implementiert eine HTTP-Methode als universellen Proxy zur Advoware-API.

## Übersicht

Die Proxy-Steps fungieren als transparente Schnittstelle zwischen Clients und der Advoware-API. Sie handhaben Authentifizierung, Fehlerbehandlung und Logging automatisch.

## Steps

### 1. GET Proxy (`advoware_api_proxy_get_step.py`)

**Zweck:** Universeller Proxy für GET-Requests an die Advoware-API.

**Konfiguration:**
- **Type:** api
- **Name:** Advoware Proxy GET
- **Path:** `/advoware/proxy`
- **Method:** GET
- **Flows:** advoware

**Funktionalität:**
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
- Übergibt alle anderen Query-Parameter als API-Parameter
- Gibt das Ergebnis als JSON zurück

**Beispiel Request:**
```
GET /advoware/proxy?endpoint=employees&limit=10&offset=0
```

**Response:**
```json
{
  "result": {
    "data": [...],
    "total": 100
  }
}
```

### 2. POST Proxy (`advoware_api_proxy_post_step.py`)

**Zweck:** Universeller Proxy für POST-Requests an die Advoware-API.

**Konfiguration:**
- **Type:** api
- **Name:** Advoware Proxy POST
- **Path:** `/advoware/proxy`
- **Method:** POST
- **Flows:** advoware

**Funktionalität:**
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
- Verwendet den Request-Body als JSON-Daten für die API
- Erstellt neue Ressourcen in Advoware

**Beispiel Request:**
```
POST /advoware/proxy?endpoint=employees
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}
```

### 3. PUT Proxy (`advoware_api_proxy_put_step.py`)

**Zweck:** Universeller Proxy für PUT-Requests an die Advoware-API.

**Konfiguration:**
- **Type:** api
- **Name:** Advoware Proxy PUT
- **Path:** `/advoware/proxy`
- **Method:** PUT
- **Flows:** advoware

**Funktionalität:**
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
- Verwendet den Request-Body als JSON-Daten für Updates
- Aktualisiert bestehende Ressourcen in Advoware

**Beispiel Request:**
```
PUT /advoware/proxy?endpoint=employees/123
Content-Type: application/json

{
  "name": "John Smith",
  "email": "johnsmith@example.com"
}
```

### 4. DELETE Proxy (`advoware_api_proxy_delete_step.py`)

**Zweck:** Universeller Proxy für DELETE-Requests an die Advoware-API.

**Konfiguration:**
- **Type:** api
- **Name:** Advoware Proxy DELETE
- **Path:** `/advoware/proxy`
- **Method:** DELETE
- **Flows:** advoware

**Funktionalität:**
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
- Löscht Ressourcen in Advoware

**Beispiel Request:**
```
DELETE /advoware/proxy?endpoint=employees/123
```

## Gemeinsame Features

### Authentifizierung
Alle Steps verwenden den `AdvowareAPI` Service für automatische Token-Verwaltung und Authentifizierung.

### Fehlerbehandlung
- **400 Bad Request:** Fehlender `endpoint` Parameter
- **500 Internal Server Error:** API-Fehler oder Exceptions

### Logging
Detaillierte Logs für:
- Eingehende Requests
- API-Calls an Advoware
- Fehler und Exceptions

### Sicherheit
- Keine direkte Weitergabe sensibler Daten
- Authentifizierung über Service-Layer
- Input-Validation für erforderliche Parameter

## Testing

### Unit Tests
```bash
# Test GET Proxy
curl -X GET "http://localhost:3000/advoware/proxy?endpoint=employees"

# Test POST Proxy
curl -X POST "http://localhost:3000/advoware/proxy?endpoint=employees" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Employee"}'

# Test PUT Proxy
curl -X PUT "http://localhost:3000/advoware/proxy?endpoint=employees/1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Employee"}'

# Test DELETE Proxy
curl -X DELETE "http://localhost:3000/advoware/proxy?endpoint=employees/1"
```

### Integration Tests
Überprüfen Sie die Logs für korrekte API-Calls:
```bash
motia logs | grep "Proxying request to Advoware"
```

## Konfiguration

### Umgebungsvariablen
Stellen Sie sicher, dass folgende Variablen gesetzt sind:
- `ADVOWARE_BASE_URL`
- `ADVOWARE_USERNAME`
- `ADVOWARE_PASSWORD`

### Dependencies
- `services/advoware.py` - Advoware API Client
- `config.py` - Konfigurationsmanagement

## Erweiterungen

### Geplante Features
- Request/Response Caching
- Rate Limiting
- Request Validation Schemas
- Batch-Operations Support

### Custom Endpoints
Für spezifische Endpoints können zusätzliche Steps erstellt werden, die direkt auf bestimmte Ressourcen zugreifen.