Update README and add detailed documentation for Advoware integration and calendar sync
This commit is contained in:
bsiggel
314
steps/advoware_proxy/README.md
Normal file
314
steps/advoware_proxy/README.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 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 mit **Motia III v1.0-RC**.
|
||||
|
||||
## Ü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:**
|
||||
```python
|
||||
config = {
|
||||
'name': 'Advoware Proxy GET',
|
||||
'flows': ['advoware'],
|
||||
'triggers': [
|
||||
http('GET', '/advoware/proxy')
|
||||
],
|
||||
'enqueues': []
|
||||
}
|
||||
```
|
||||
|
||||
**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:**
|
||||
```bash
|
||||
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:**
|
||||
```python
|
||||
config = {
|
||||
'name': 'Advoware Proxy POST',
|
||||
'flows': ['advoware'],
|
||||
'triggers': [
|
||||
http('POST', '/advoware/proxy')
|
||||
],
|
||||
'enqueues': []
|
||||
}
|
||||
```
|
||||
|
||||
**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:**
|
||||
```bash
|
||||
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:**
|
||||
```python
|
||||
config = {
|
||||
'name': 'Advoware Proxy PUT',
|
||||
'flows': ['advoware'],
|
||||
'triggers': [
|
||||
http('PUT', '/advoware/proxy')
|
||||
],
|
||||
'enqueues': []
|
||||
}
|
||||
```
|
||||
|
||||
**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:**
|
||||
```bash
|
||||
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:**
|
||||
```python
|
||||
config = {
|
||||
'name': 'Advoware Proxy DELETE',
|
||||
'flows': ['advoware'],
|
||||
'triggers': [
|
||||
http('DELETE', '/advoware/proxy')
|
||||
],
|
||||
'enqueues': []
|
||||
}
|
||||
```
|
||||
|
||||
**Funktionalität:**
|
||||
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
|
||||
- Löscht Ressourcen in Advoware
|
||||
|
||||
**Beispiel Request:**
|
||||
```bash
|
||||
DELETE /advoware/proxy?endpoint=employees/123
|
||||
```
|
||||
|
||||
## Gemeinsame Features
|
||||
|
||||
### Authentifizierung
|
||||
Alle Steps verwenden den `AdvowareService` für automatische Token-Verwaltung und Authentifizierung:
|
||||
- HMAC-512 basierte Signatur
|
||||
- Token-Caching in Redis (55 Minuten Lifetime)
|
||||
- Automatischer Token-Refresh bei 401-Errors
|
||||
|
||||
### Fehlerbehandling
|
||||
- **400 Bad Request:** Fehlender `endpoint` Parameter
|
||||
- **500 Internal Server Error:** API-Fehler oder Exceptions
|
||||
- **401 Unauthorized:** Automatischer Token-Refresh und Retry
|
||||
|
||||
### Logging
|
||||
Detaillierte Logs via `ctx.logger` für:
|
||||
- Eingehende Requests
|
||||
- API-Calls an Advoware
|
||||
- Fehler und Exceptions
|
||||
- Token-Management
|
||||
|
||||
Alle Logs sind in der **iii Console** sichtbar.
|
||||
|
||||
### Sicherheit
|
||||
- Keine direkte Weitergabe sensibler Daten
|
||||
- Authentifizierung über Service-Layer
|
||||
- Input-Validation für erforderliche Parameter
|
||||
- HMAC-512 Signatur für alle API-Requests
|
||||
|
||||
## Handler-Struktur (Motia III)
|
||||
|
||||
Alle Steps folgen dem gleichen Pattern:
|
||||
|
||||
```python
|
||||
from motia import http, ApiRequest, ApiResponse, FlowContext
|
||||
from services.advoware_service import AdvowareService
|
||||
|
||||
config = {
|
||||
'name': 'Advoware Proxy {METHOD}',
|
||||
'flows': ['advoware'],
|
||||
'triggers': [
|
||||
http('{METHOD}', '/advoware/proxy')
|
||||
],
|
||||
'enqueues': []
|
||||
}
|
||||
|
||||
async def handler(request: ApiRequest, ctx: FlowContext) -> ApiResponse:
|
||||
# Extract endpoint from query params
|
||||
endpoint = request.query_params.get('endpoint')
|
||||
|
||||
if not endpoint:
|
||||
return ApiResponse(
|
||||
status=400,
|
||||
body={'error': 'Missing required query parameter: endpoint'}
|
||||
)
|
||||
|
||||
# Call Advoware API
|
||||
advoware_service = AdvowareService()
|
||||
result = await advoware_service.{method}(endpoint, **params)
|
||||
|
||||
return ApiResponse(status=200, body={'result': result})
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
```bash
|
||||
# Test GET Proxy
|
||||
curl -X GET "http://localhost:3111/advoware/proxy?endpoint=employees"
|
||||
|
||||
# Test POST Proxy
|
||||
curl -X POST "http://localhost:3111/advoware/proxy?endpoint=employees" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "Test Employee"}'
|
||||
|
||||
# Test PUT Proxy
|
||||
curl -X PUT "http://localhost:3111/advoware/proxy?endpoint=employees/1" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "Updated Employee"}'
|
||||
|
||||
# Test DELETE Proxy
|
||||
curl -X DELETE "http://localhost:3111/advoware/proxy?endpoint=employees/1"
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
Überprüfen Sie die Logs in der iii Console:
|
||||
```bash
|
||||
# Check logs
|
||||
curl http://localhost:3111/_console/logs
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Umgebungsvariablen
|
||||
Stellen Sie sicher, dass folgende Variablen gesetzt sind:
|
||||
```env
|
||||
ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
|
||||
ADVOWARE_PRODUCT_ID=64
|
||||
ADVOWARE_APP_ID=your_app_id
|
||||
ADVOWARE_API_KEY=your_api_key
|
||||
ADVOWARE_KANZLEI=your_kanzlei
|
||||
ADVOWARE_DATABASE=your_database
|
||||
ADVOWARE_USER=your_user
|
||||
ADVOWARE_ROLE=2
|
||||
ADVOWARE_PASSWORD=your_password
|
||||
ADVOWARE_TOKEN_LIFETIME_MINUTES=55
|
||||
ADVOWARE_API_TIMEOUT_SECONDS=30
|
||||
|
||||
# Redis (für Token-Caching)
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
REDIS_DB=0
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
- `services/advoware_service.py` - Advoware API Client mit HMAC Auth
|
||||
- `config.py` - Konfigurationsmanagement
|
||||
- `motia` - Motia III Python SDK
|
||||
- `asyncpg` - PostgreSQL Client
|
||||
- `redis` - Redis Client für Token-Caching
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
### Geplante Features
|
||||
- Request/Response Caching für häufige Queries
|
||||
- Rate Limiting pro Client
|
||||
- Request Validation Schemas mit Pydantic
|
||||
- Batch-Operations Support
|
||||
|
||||
### Custom Endpoints
|
||||
Für spezifische Endpoints können zusätzliche Steps erstellt werden, die direkt auf bestimmte Ressourcen zugreifen und erweiterte Validierung/Transformation bieten.
|
||||
|
||||
## Architektur
|
||||
|
||||
```
|
||||
Client Request
|
||||
│
|
||||
▼
|
||||
HTTP Trigger (http('METHOD', '/advoware/proxy'))
|
||||
│
|
||||
▼
|
||||
Handler (ApiRequest → ApiResponse)
|
||||
│
|
||||
├─► Extract 'endpoint' from query params
|
||||
├─► Extract other params/body
|
||||
│
|
||||
▼
|
||||
AdvowareService
|
||||
│
|
||||
├─► Check Redis for valid token
|
||||
├─► If expired: Get new token (HMAC-512 auth)
|
||||
├─► Build HTTP request
|
||||
│
|
||||
▼
|
||||
Advoware API
|
||||
│
|
||||
▼
|
||||
Response → Transform → Return ApiResponse
|
||||
```
|
||||
|
||||
## Migration Notes
|
||||
|
||||
Dieses System wurde von **Motia v0.17** nach **Motia III v1.0-RC** migriert:
|
||||
|
||||
### Wichtige Änderungen:
|
||||
- ✅ `type: 'api'` → `triggers: [http('METHOD', 'path')]`
|
||||
- ✅ `ApiRouteConfig` → `StepConfig` mit `as const satisfies`
|
||||
- ✅ `Handlers['StepName']` → `Handlers<typeof config>`
|
||||
- ✅ `context` → `ctx`
|
||||
- ✅ `req` dict → `ApiRequest` typed object
|
||||
- ✅ Return dict → `ApiResponse` typed object
|
||||
- ✅ `method`, `path` moved into trigger
|
||||
- ✅ Motia Workbench → iii Console
|
||||
|
||||
### Kompatibilität:
|
||||
- ✅ Alle 4 Proxy Steps vollständig migriert
|
||||
- ✅ AdvowareService kompatibel (keine Änderungen)
|
||||
- ✅ Redis Token-Caching unverändert
|
||||
- ✅ HMAC-512 Auth unverändert
|
||||
- ✅ API-Endpoints identisch
|
||||
Reference in New Issue
Block a user