From ece6b4925473f404910d12d0ef07243f85015348 Mon Sep 17 00:00:00 2001 From: michael Date: Wed, 10 Sep 2025 13:58:40 +0200 Subject: [PATCH] =?UTF-8?q?API=20Documentation=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- API-Documentation.md | 202 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 API-Documentation.md diff --git a/API-Documentation.md b/API-Documentation.md new file mode 100644 index 0000000..21d35c6 --- /dev/null +++ b/API-Documentation.md @@ -0,0 +1,202 @@ +# API Documentation + +**Furt Gateway v0.1.2 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.dragons-at-work.de +Development: http://localhost:7811 +``` + +## Authentication + +Alle API-Endpunkte (außer `/health`) erfordern Authentifizierung via API-Key: + +```http +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:** +```http +X-RateLimit-Limit: 60 +X-RateLimit-Remaining: 45 +X-RateLimit-Reset: 1632150000 +``` + +## Request/Response Format + +### Standard Request Format + +```json +{ + "name": "John Doe", + "email": "john@example.com", + "message": "Your message content" +} +``` + +### Standard Success Response + +```json +{ + "success": true, + "message": "Operation completed successfully", + "request_id": "1632150000-1234", + "data": { /* endpoint-specific data */ } +} +``` + +### Standard Error Response + +```json +{ + "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: + +```http +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) + +```javascript +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) + +```bash +curl -X POST https://api.dragons-at-work.de/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 + +```html +{{< furt-contact-form + api-endpoint="https://api.dragons-at-work.de/v1/mail/send" + api-key="your-api-key" + success-url="/contact/thanks/" +>}} +``` + +## Service-Specific Documentation + +- **[Mail Service API](Mail-Service-API.md)** - Detaillierte Mail-Service-Dokumentation +- **[Health Endpoint](Health-Endpoint.md)** - System-Monitoring und Diagnostics + +## Current Limitations (v0.1.2) + +- **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: + +```bash +# 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. \ No newline at end of file