Concevoir une API de pointage biometrique

Principes de conception

Lors de la conception de l'API de PunchConnect, nous avons etudie les API que nous admirons le plus : Stripe pour la coherence, Twilio pour les webhooks et GitHub pour l'experience developpeur. Trois principes en ont emerge :

1. Etre previsible — nommage coherent, formats de reponse et codes d'erreur uniformes sur chaque endpoint

2. Etre temps reel — des webhooks pour les evenements, pas du polling. Les developpeurs doivent reagir aux evenements, pas les verifier.

3. Etre resilient — chaque operation doit pouvoir etre retentee en toute securite. Cles d'idempotence, deduplication et livraison au moins une fois.

Garanties de livraison des webhooks

PunchConnect garantit une livraison au moins une fois pour tous les evenements webhook. Voici comment cela fonctionne :

Lorsqu'un evenement de pointage se produit, il est ecrit dans une file d'attente durable. Un worker de livraison le recupere et envoie la requete HTTP POST a votre URL de rappel. Si votre serveur repond avec un code 2xx, l'evenement est marque comme livre.

Si votre serveur est hors service ou repond avec un code 5xx, l'evenement est renvoye avec un backoff exponentiel : 1 min, 5 min, 30 min, 2 heures, 12 heures, 72 heures. Apres epuisement de toutes les tentatives, l'evenement est marque comme echoue et vous etes notifie par e-mail.

Strategie de limitation de debit

Nous utilisons un limiteur de debit a fenetre glissante avec des valeurs par defaut genereux : 1 000 appels API par appareil par jour pour les endpoints REST, et illimite pour les webhooks entrants (appareil vers PunchConnect).

Les limites de debit sont communiquees via des en-tetes standards : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Lorsque vous atteignez la limite, vous recevez une reponse 429 avec un en-tete Retry-After.

Idempotence

Tous les endpoints mutants (POST, PUT, DELETE) acceptent un en-tete Idempotency-Key. Si vous envoyez la meme requete avec la meme cle dans les 24 heures, vous obtenez la reponse mise en cache au lieu de creer un doublon.

C'est essentiel pour les commandes d'appareils. Si vous envoyez une commande "synchroniser les employes" et que votre reseau coupe avant de recevoir la reponse, vous pouvez renvoyer la requete en toute securite sans declencher accidentellement une double synchronisation.

Lecons apprises

La lecon la plus importante : les donnees biometriques du monde reel sont desordonnees. Les appareils envoient des pointages en double, des horodatages desordonnes et parfois des donnees corrompues. Notre API normalise et deduplique avant que votre webhook ne les recoive, de sorte que vous obtenez des donnees propres et fiables.