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:

{
  "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

# 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:

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.