La migliore API di verifica è quella che regge sotto carico.

Ci costruirete sopra per anni, quindi leggetelo prima di tutto il resto. Uno schema ridotto a un solo campo enumerato costringe ogni consumatore a ricostruire la sfumatura che il fornitore aveva già e ha buttato.

Quello che volete è un verdetto su cui fare uno switch, un punteggio numerico di cui fissate voi la soglia, e motivi leggibili dalla macchina sotto entrambi. Sono quei motivi a permettere di trattare diversamente un indirizzo di ruolo, una casella piena e un dominio che vi ha messo in greylisting, senza tre integrazioni separate.

• Un verdetto di raggiungibilità stabile tra le versioni, che si proietti pulito su consenti, avvisa e blocca
• Un punteggio, così la vostra soglia è un valore di configurazione e non una decisione del fornitore
• Codici di motivo documentati ed enumerabili, non testo libero in inglese
• Un’azione consigliata, utile alle parti del prodotto che non sono codice
• Indicatori per le condizioni che vi interessano: catch-all, usa e getta, ruolo, suggerimenti sui refusi

La verifica a livello di casella dialoga con un terzo via SMTP, e alcuni server destinatari sono lenti di proposito. Un controllo singolo è di solito rapido e ogni tanto no, il che è un problema se sta sul percorso critico di una registrazione.

Progettate per questo invece di sperare. Fissate un timeout lato client che vi va bene mostrare, trattate lo scadere come non concludente e non come non valido, e lasciate passare la registrazione con un contrassegno invece di respingere un cliente vero perché un server era occupato. Poi ricontrollate in modo asincrono e agite sulla seconda risposta.

Chiedete a ogni fornitore il timeout pubblicato e cosa fa quando lo raggiunge. Chi restituisce non valido sul proprio timeout sta trasformando in silenzio il suo problema di infrastruttura nella vostra registrazione persa.

Ci sono tre tipi di fallimento e richiedono tre reazioni diverse dal vostro codice. Confonderli è la causa più comune di un’integrazione di verifica che va storta in produzione.

Una richiesta malformata è un vostro bug e non va mai ritentata. Un limite di frequenza o un guasto temporaneo a monte va ritentato con attesa crescente. E un verdetto non concludente non è affatto un errore: la chiamata è riuscita, la risposta è che non c’era risposta disponibile, e ritentare subito produrrà la stessa non risposta spendendo un altro credito.

• 4xx per i vostri errori, con un codice stabile e leggibile dalla macchina, non una frase
• 429 con un’intestazione che dica quando tornare, invece di un rifiuto secco
• 5xx solo per i guasti del fornitore, così il vostro monitoraggio può fidarsi
• Risultati non concludenti restituiti come 200 con verdetto sconosciuto, perché è quello che è successo

Un controllo singolo è sincrono e vive dentro una richiesta. Un lotto è asincrono e vive in una coda, a volte per un’ora. Trattare il secondo come il primo significa finire a interrogare un endpoint di stato ogni secondo per quaranta minuti.

Verificate che il lato lotti sia una vera API a job: inviare, ricevere un id, interrogare o ricevere una callback, poi scaricare. Verificate cosa succede se inviate due volte lo stesso file, qual è il tetto di dimensione e se l’esportazione conserva le vostre colonne. Quelle tre risposte fanno risparmiare più tempo di sviluppo della differenza di prezzo tra due fornitori di questo mercato.

Nessuno è interessante fino al giorno in cui lo diventa, e a quel punto l’integrazione è già scritta.

• Rotazione delle chiavi. Più di una chiave attiva, revocabili separatamente, senza interruzioni.
• Non chiamate mai un’API di verifica dal browser. La chiave è un segreto, e una chiave pubblica è il saldo crediti di qualcun altro.
• Conservazione. Per quanto viene tenuto l’indirizzo che avete inviato, e se potete accorciare quel periodo.
• Idempotenza all’invio di un lotto, perché un intoppo di rete non vi fatturi due volte lo stesso file.
• Se lo stesso motore sta dietro al pannello e all’API. Altrimenti il vostro controllo puntuale non dimostra nulla sulla produzione.

Un token, un endpoint per un indirizzo e uno per un lotto. POST /v1/check_email restituisce verdetto, punteggio, codici di motivo e azione consigliata; POST /v1/bulk prende una lista e restituisce un job da interrogare. Entrambi sono documentati con esempi eseguibili invece che con uno schema grezzo.

Le chiavi API arrivano con qualsiasi piano a pagamento, mensile o a consumo, invece di partire da una fascia che la maggior parte dei team non usa. Un account gratuito verifica dal pannello, il che basta per vedere la forma della risposta prima di scrivere codice.