Checklist pratica per integrare un’API di IP lookup

Aggiungere una chiamata di IP intelligence richiede dieci minuti. Gestirne tutti i casi limite può richiedere sei mesi. Questa è la checklist che vorremmo vedere superata da ogni nuova integrazione.

1. Recuperare l’indirizzo del client corretto

Prima di tutto, assicuratevi di interrogare l’indirizzo giusto. Dietro un load balancer o una CDN, remoteAddr spesso punta al vostro proxy, non all’utente finale. Serve leggere la catena degli header forwarded, ma fidandosi solo degli hop sotto il vostro controllo: in pratica, va preso il primo indirizzo non fidato partendo da destra, non quello più a sinistra, che può essere falsificato. Fare lookup sull’indirizzo sbagliato è peggio che non farlo: dà una falsa sensazione di autorevolezza.

Gestite correttamente anche IPv6, inclusi gli indirizzi tra parentesi quadre e la notazione IPv4-mapped.

2. Impostare un timeout rigido

Definite un budget — per un percorso di signup, 300–800 ms è di solito un intervallo ragionevole — e applicatelo lato client. Un controllo di rischio che resta appeso trasforma una funzione di sicurezza in un disservizio.

3. Decidere fail-open o fail-closed, per singolo flusso

Mettetelo nero su bianco per ogni punto in cui fate la chiamata:

• Signup / login → fail open. Non bloccate l’intera base utenti perché una dipendenza è lenta.
• Payout o prelievo → fail closed, oppure accodamento per revisione manuale. Quando il denaro esce, un ritardo è accettabile.

Applicare una sola policy a tutta l’applicazione è il modo più rapido per ritrovarsi con un outage o con una perdita economica.

4. Usare la cache

Lo stesso indirizzo vi colpirà più volte nell’arco di pochi minuti. Mettete in cache i risultati per una finestra sensata — un’ora è un buon punto di partenza — usando l’indirizzo come chiave. Riducete insieme latenza, costi e carico sul provider. Rendete configurabile il TTL, così potete accorciarlo durante un incidente e allungarlo nei picchi di traffico.

5. Spostare il lookup fuori dal percorso critico, quando possibile

Non tutti i controlli devono bloccare la risposta. Per pulizia delle analytics, arricchimento dei log e revisioni a posteriori, accodate l’indirizzo e arricchitelo in modo asincrono. Riservate le chiamate sincrone alle decisioni che dovete prendere in quel preciso momento.

6. Gestire le risposte problematiche

Elencatele e testatele: rate limit, chiave non valida, indirizzo sconosciuto, range privato o riservato, input malformato. Ognuna deve produrre un esito definito nel vostro codice, non un’eccezione non gestita dentro un request handler.

I range privati meritano una nota a parte: 10.x, 192.168.x, 127.0.0.1 e simili compariranno in sviluppo e nelle catene proxy configurate male. Intercettateli prima di consumare una chiamata API.

7. Proteggere la chiave

La chiave API deve stare nella configurazione server-side, mai in JavaScript eseguito nel browser o dentro un bundle mobile. Tutto ciò che viene distribuito al client va considerato pubblico. Ruotate le chiavi quando cambia il personale e usate chiavi separate per ogni ambiente, così potete revocarne una senza rompere tutto il resto.

8. Salvare il verdetto insieme alla decisione

Registrate score e flag accanto all’azione che avete intrapreso. Quando, mesi dopo, vi chiederete “perché abbiamo rifiutato quest’ordine a marzo?”, la risposta deve essere nel vostro database, non ricostruita dalla dashboard di un provider.

9. Monitorare le vostre metriche

Tracciate percentili di latenza delle chiamate, tasso di errore, cache hit rate e consumo della quota. Una deriva silenziosa in uno di questi indicatori spesso arriva prima di un incidente visibile.

10. Testare con indirizzi reali

Inserite nella test suite un indirizzo datacenter noto, un’uscita TOR nota, un indirizzo residenziale e un indirizzo mobile. Fate asserzioni sulla classificazione, non sugli score esatti. I punteggi cambiano; le categorie sono molto più stabili.

Passate questa lista una volta sola e l’integrazione durerà più dello sprint che l’ha prodotta.