Unsere API ist mit Hono auf Cloudflare Workers aufgebaut, optimiert für niedrige Latenz und globale Verteilung. So bauen und pflegen wir sie.
Hono Framework
Wir haben Hono wegen seines leichten Footprints und Edge-First-Designs gewählt:
- Kleines Bundle: Hono fügt minimalen Overhead zur Worker-Größe hinzu und hält Cold Starts schnell.
- Vertraute Muster: Express-ähnliches Routing macht das Onboarding für Entwickler einfach.
- Eingebaute Middleware: CORS, Komprimierung und Logging funktionieren out of the box.
- Typsicherheit: Volle TypeScript-Unterstützung mit Anfrage-/Antwort-Typisierung.
Edge-First-Design
Jede API-Entscheidung berücksichtigt Edge-Deployment-Einschränkungen:
- Zustandslose Handler: Keine serverseitigen Sessions oder lokaler Storage zwischen Anfragen.
- Externer Zustand: Aller Zustand lebt in Supabase (SQL), Cloudflare KV (Key-Value) oder R2 (Blobs).
- Cold-Start-Optimierung: Lazy-Initialisierung schwerer Clients (Stripe, Supabase) nur bei Bedarf.
- Regionales Routing: Cloudflare routet Anfragen automatisch zum nächsten Edge-Standort.
Anfrage-Validierung
Zod bietet Runtime-Typsicherheit für alle eingehenden Daten:
- Schema-Definitionen: Jeder Endpunkt definiert seine erwartete Eingabeform mit Zod-Schemas.
- Automatisches Parsen: Ungültige Anfragen schlagen schnell mit klaren Fehlermeldungen fehl.
- Typ-Inferenz: TypeScript-Typen werden aus Schemas abgeleitet, um Konsistenz sicherzustellen.
- Transformationen: Zod verarbeitet Koerzion (String zu Zahl) und Standardwerte sauber.
Fehlerbehandlung
Konsistente Fehlerantworten erleichtern das Debugging:
- Strukturiertes Format: Alle Fehler geben JSON mit error, message und optionalen Details zurück.
- HTTP-Status-Codes: Wir verwenden angemessene Codes (400 für Validierung, 401 für Auth, 403 für Berechtigungen, 429 für Rate-Limits).
- Fehlerverfolgung: Ausnahmen werden mit Anfrage-Kontext für Debugging protokolliert.
- Nutzerfreundliche Nachrichten: Technische Details werden protokolliert, aber nicht an Clients weitergegeben.
Rate-Limiting
Unsere Rate-Limiting-Strategie schützt das System und ist dabei fair:
- Gestufte Limits: Verschiedene Limits für Tracking-Endpunkte (hoch), API-Endpunkte (mittel) und Auth-Endpunkte (niedrig).
- Per-Key-Tracking: API-Schlüssel haben individuelle Kontingente basierend auf der Abonnementstufe.
- Gleitendes Fenster: Limits werden über rollende Zeitfenster berechnet, nicht feste Perioden.
- Sanfter Abbau: Rate-begrenzte Anfragen erhalten Retry-After-Header.
Endpunkt-Organisation
Routen sind nach Domain für Wartbarkeit organisiert:
- /e/:trackingCode — Öffentliches Tracking (werbeblocker-freundlich)
- /api/analytics/* — Dashboard-Datenabfragen
- /api/replay/* — Session-Replay-Verwaltung
- /api/billing/* — Stripe-Integration
- /api/team/:teamId/* — Team-bezogene Operationen
- /api/external/v1/* — Drittanbieter-API-Zugriff
- /api/cron/* — Geplante Aufgaben-Trigger (Webhook-Auth)