API Documentation
Furt Gateway v0.1.4 API Reference
Übersicht
Furt bietet eine REST-API für die Integration mit Websites und Anwendungen. Die API ist multi-tenant-fähig - jeder API-Key erhält seine eigene Konfiguration und isolierte Services.
Base URL
Production: https://api.example.com
Development: http://localhost:7811
Authentication
Alle API-Endpunkte (außer /health) erfordern Authentifizierung via API-Key:
X-API-Key: your-api-key-here
Warum API-Keys: Jeder API-Key definiert eine isolierte Tenant-Konfiguration. Dadurch kann ein Furt-Gateway mehrere Websites/Projekte gleichzeitig bedienen, ohne dass sich die Konfigurationen vermischen.
Available Endpoints
Core Endpoints
| Endpoint | Method | Authentication | Description |
|---|---|---|---|
/health |
GET | None | System health and status |
/v1/mail/send |
POST | Required | Multi-tenant mail service |
/auth/status |
GET | Required | Authentication verification |
/test |
GET | Optional | Development testing (configurable) |
Rate Limiting
Alle authentifizierten Endpunkte unterliegen Rate-Limiting. Die Limits sind pro API-Key konfigurierbar und standardmäßig auf 60 Requests pro Minute gesetzt.
Rate-Limit-Headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1632150000
Request/Response Format
Standard Request Format
{
"name": "John Doe",
"email": "john@example.com",
"message": "Your message content"
}
Standard Success Response
{
"success": true,
"message": "Operation completed successfully",
"request_id": "1632150000-1234",
"data": { /* endpoint-specific data */ }
}
Standard Error Response
{
"success": false,
"error": "Descriptive error message",
"code": "ERROR_CODE",
"request_id": "1632150000-1234"
}
Error Codes
Furt verwendet strukturierte Error-Codes für programmatische Fehlerbehandlung:
| Code | Description | HTTP Status |
|---|---|---|
VALIDATION_ERROR |
Request validation failed | 400 |
UNAUTHORIZED |
Invalid or missing API key | 401 |
RATE_LIMIT_EXCEEDED |
Too many requests | 429 |
CONFIG_ERROR |
Server configuration issue | 500 |
SMTP_ERROR |
Mail delivery failed | 500 |
MISSING_BODY |
Request body required but missing | 400 |
INVALID_JSON |
Request body is not valid JSON | 400 |
CORS Support
Furt sendet automatisch CORS-Headers für Frontend-Integration:
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-API-Key
Access-Control-Max-Age: 86400
Warum Permissive CORS: Da Furt als API-Gateway für verschiedene Websites dient, ist eine restriktive CORS-Policy unpraktisch. Die Authentifizierung erfolgt über API-Keys, nicht über Origin-Validation.
Request Tracking
Jeder API-Request erhält eine eindeutige Request-ID für Logging und Debugging:
Format: {unix_timestamp}-{random_4_digits}
Beispiel: 1632150000-1234
Die Request-ID wird in allen Responses zurückgegeben und in den Server-Logs mitgeführt.
Multi-Tenant Architecture
Warum Multi-Tenant: Ein Furt-Gateway kann mehrere Websites gleichzeitig bedienen. Jeder API-Key definiert:
- Eigene SMTP-Konfiguration
- Eigene Mail-Empfänger
- Eigene Subject-Präfixe
- Eigene Rate-Limits
- Isolierte Logs und Metriken
Beispiel-Szenario:
API-Key "website-a" → Mails an admin@website-a.com
API-Key "website-b" → Mails an contact@website-b.org
API-Key "blog-xyz" → Mails an hello@blog-xyz.net
Alle drei nutzen denselben Furt-Gateway, aber komplett isolierte Konfigurationen.
Integration Examples
JavaScript (Frontend)
async function sendContactForm(formData) {
const response = await fetch('/v1/mail/send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your-api-key'
},
body: JSON.stringify(formData)
});
const result = await response.json();
return result;
}
curl (Testing)
curl -X POST https://api.example.com/v1/mail/send \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"name":"Test","email":"test@example.com","message":"Test message"}'
Hugo Shortcode Integration
{{< furt-contact-form
api-endpoint="https://api.example.com/v1/mail/send"
api-key="your-api-key"
success-url="/contact/thanks/"
>}}
Service-Specific Documentation
- Mail Service API - Detaillierte Mail-Service-Dokumentation
- Health Endpoint - System-Monitoring und Diagnostics
Current Limitations (v0.1.4)
- Service Integration: Aktuell ist nur der Mail-Service (formular2mail) integriert
- Service Discovery: Andere Services können sich noch nicht dynamisch registrieren
- Configuration API: Tenant-Konfiguration nur via Config-Datei möglich
Roadmap: Service-Discovery und Configuration-API sind für zukünftige Versionen geplant.
Development
Für lokale Entwicklung und Testing:
# Development-Server starten
sudo systemctl start furt
# API-Tests
curl http://localhost:7811/health
curl -H "X-API-Key: test" http://localhost:7811/auth/status
Development-Endpoint: Der /test Endpoint ist nur verfügbar wenn in der Konfiguration aktiviert. Er dient zum Testen der Request-Verarbeitung ohne Side-Effects.