API Documentation hinzugefügt
parent
7694641aa9
commit
ece6b49254
1 changed files with 202 additions and 0 deletions
202
API-Documentation.md
Normal file
202
API-Documentation.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue