Notre API est construite avec Hono sur Cloudflare Workers, optimisée pour une faible latence et une distribution mondiale. Voici comment nous la construisons et la maintenons.
Framework Hono
Nous avons choisi Hono pour son empreinte légère et sa conception edge-first :
- Bundle minuscule : Hono ajoute une surcharge minimale à la taille des Workers, gardant les démarrages à froid rapides.
- Patterns familiers : Le routage similaire à Express facilite l'intégration des développeurs.
- Middleware intégré : CORS, compression et journalisation fonctionnent out of the box.
- Sécurité des types : Support TypeScript complet avec typage des requêtes/réponses.
Conception edge-first
Chaque décision API prend en compte les contraintes du déploiement edge :
- Handlers sans état : Pas de sessions côté serveur ni de stockage local entre les requêtes.
- État externe : Tout l'état vit dans Supabase (SQL), Cloudflare KV (clé-valeur) ou R2 (blobs).
- Optimisation du démarrage à froid : Initialisation paresseuse des clients lourds (Stripe, Supabase) uniquement quand nécessaire.
- Routage régional : Cloudflare route automatiquement les requêtes vers l'emplacement edge le plus proche.
Validation des requêtes
Zod fournit une sécurité de type à l'exécution pour toutes les données entrantes :
- Définitions de schémas : Chaque endpoint définit la forme attendue de ses entrées avec des schémas Zod.
- Parsing automatique : Les requêtes invalides échouent rapidement avec des messages d'erreur clairs.
- Inférence de types : Les types TypeScript sont dérivés des schémas, assurant la cohérence.
- Transformations : Zod gère proprement la coercition (chaîne vers nombre) et les valeurs par défaut.
Gestion des erreurs
Des réponses d'erreur cohérentes facilitent le débogage :
- Format structuré : Toutes les erreurs retournent du JSON avec error, message et details optionnel.
- Codes de statut HTTP : Nous utilisons les codes appropriés (400 pour la validation, 401 pour l'auth, 403 pour les permissions, 429 pour les limites de débit).
- Suivi des erreurs : Les exceptions sont journalisées avec le contexte de la requête pour le débogage.
- Messages conviviaux : Les détails techniques sont journalisés mais non exposés aux clients.
Limitation de débit
Notre stratégie de limitation de débit protège le système tout en étant équitable :
- Limites par niveaux : Différentes limites pour les endpoints de suivi (élevées), API (moyennes) et auth (faibles).
- Suivi par clé : Les clés API ont des quotas individuels basés sur le niveau d'abonnement.
- Fenêtre glissante : Les limites sont calculées sur des fenêtres temporelles glissantes, pas des périodes fixes.
- Dégradation gracieuse : Les requêtes limitées reçoivent des en-têtes Retry-After.
Organisation des endpoints
Les routes sont organisées par domaine pour la maintenabilité :
- /e/:trackingCode — Suivi public (résistant aux bloqueurs de publicités)
- /api/analytics/* — Requêtes de données du tableau de bord
- /api/replay/* — Gestion du replay de session
- /api/billing/* — Intégration Stripe
- /api/team/:teamId/* — Opérations délimitées à l'équipe
- /api/external/v1/* — Accès API tiers
- /api/cron/* — Déclencheurs de tâches planifiées (auth webhook)