Checklist pratique pour intégrer une API de recherche d’IP

Ajouter un appel à une API d’intelligence IP prend dix minutes. Gérer correctement tous les cas limites peut prendre six mois. Voici la checklist que toute nouvelle intégration devrait, selon nous, passer avant d’arriver en production.

1. Récupérer la bonne adresse client

Avant toute chose, assurez-vous d’interroger la bonne adresse. Derrière un load balancer ou un CDN, remoteAddr correspond souvent à votre propre proxy. Il faut donc analyser la chaîne des adresses transmises — et ne faire confiance qu’aux sauts que vous maîtrisez. En pratique, on retient l’entrée non fiable la plus à droite, plutôt que la première à gauche, facilement falsifiable. Une recherche faite sur la mauvaise adresse est pire qu’aucune recherche : elle donne une impression d’autorité alors qu’elle repose sur une donnée erronée.

Pensez aussi à gérer correctement l’IPv6, y compris les adresses entre crochets et la notation IPv4-mapped.

2. Définir un timeout strict

Fixez un budget — 300–800 ms est généralement raisonnable pour un parcours d’inscription — et imposez-le côté client. Un contrôle de risque qui reste suspendu transforme vite une mesure de sécurité en panne applicative.

3. Choisir entre fail-open et fail-closed, selon le parcours

Formalisez la règle pour chaque point d’appel :

• Inscription / connexion → fail open. Ne bloquez jamais toute votre base d’utilisateurs parce qu’une dépendance répond lentement.
• Paiement sortant ou retrait → fail closed, ou mise en file pour revue manuelle. Quand l’argent sort, un délai se justifie.

Appliquer une seule politique à toute l’application, c’est souvent la recette soit d’une indisponibilité, soit d’un incident financier.

4. Mettre en cache

La même adresse va souvent revenir plusieurs fois en quelques minutes. Mettez les résultats en cache sur une durée raisonnable — une heure constitue un bon point de départ — avec l’adresse comme clé. Vous réduisez d’un coup la latence, les coûts et la charge côté fournisseur. Rendez le TTL configurable afin de pouvoir le raccourcir pendant un incident et l’allonger lors d’un pic de trafic.

5. Sortir la recherche du chemin critique quand c’est possible

Tous les contrôles n’ont pas besoin de bloquer la réponse. Pour nettoyer des données analytiques, enrichir des logs ou mener des revues a posteriori, placez l’adresse en file d’attente et enrichissez-la de manière asynchrone. Réservez les appels synchrones aux décisions qui doivent être prises immédiatement.

6. Traiter les réponses défavorables

Listez-les et testez-les : limite de débit atteinte, clé invalide, adresse inconnue, plage privée ou réservée, entrée mal formée. Chaque cas doit produire un résultat défini dans votre code, pas une exception non gérée dans un handler de requête.

Les plages privées méritent une attention particulière : 10.x, 192.168.x, 127.0.0.1 et leurs équivalents apparaîtront en développement, mais aussi dans des chaînes de proxy mal configurées. Court-circuitez-les avant de consommer un appel API.

7. Protéger la clé

La clé API doit rester dans la configuration côté serveur, jamais dans du JavaScript exécuté par le navigateur ni dans un bundle mobile. Tout ce qui est livré à un client doit être considéré comme public. Faites tourner les clés lors des changements d’équipe, et utilisez des clés distinctes par environnement pour pouvoir en révoquer une sans tout casser.

8. Journaliser le verdict avec la décision

Stockez le score et les flags avec l’action que vous avez prise. Le jour où vous vous demanderez « pourquoi avons-nous refusé cette commande en mars ? », la réponse devra se trouver dans votre base de données, pas être reconstituée depuis le tableau de bord d’un fournisseur.

9. Surveiller vos propres métriques

Suivez les percentiles de latence des appels, le taux d’erreur, le taux de hit du cache et la consommation de quota. Une dérive discrète de l’un de ces indicateurs précède souvent un incident visible.

10. Tester avec de vraies adresses

Intégrez à votre suite de tests une adresse connue de datacenter, une sortie TOR connue, une adresse résidentielle et une adresse mobile. Vérifiez la classification plutôt que les scores exacts. Les scores évoluent ; les catégories restent plus stables.

Passez cette liste une fois sérieusement en revue, et votre intégration survivra largement au sprint qui l’a vue naître.