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