Un'API, interfaccia di programmazione delle applicazioni, è semplicemente un modo documentato con cui un software chiede dati a un altro software, o fa accadere qualcosa. Quando un CRM invia un nuovo contatto a una piattaforma di e-mail, o un e-shop comunica un ordine a un sistema di contabilità, stanno usando API.
Tre pattern comuni
Richiesta / risposta
Un sistema chiede, l'altro risponde: "dammi questo cliente", "crea questo ordine". Semplice e prevedibile, ma richiede che una parte sappia quando chiedere.
Webhook
Invece di chiedere ripetutamente, il sistema di origine invia un evento a un URL quando accade qualcosa: "è stata creata una nuova fattura", "un pagamento è andato a buon fine". Latenza inferiore e maggiore efficienza per i flussi guidati dagli eventi.
Sincronizzazione programmata
Processi periodici spostano i dati in batch, ogni ora, ogni notte, ogni settimana. Utile quando la freschezza non è critica e un push è poco pratico.
La maggior parte delle integrazioni del mondo reale combina almeno due di questi.
Cosa rende affidabile un'integrazione
- Chiara proprietà dei dati. Un sistema è la fonte di verità per ciascun dato. Gli altri ne ricevono copie.
- Operazioni idempotenti. Ripetere due volte la stessa chiamata produce lo stesso risultato, essenziale per i webhook e le reti instabili.
- Gestione degli errori visibile. I fallimenti finiscono dove un essere umano può vederli, non in un log silenzioso che nessuno legge.
- Rate limit rispettati. Le buone integrazioni rallentano quando l'altra parte è lenta o limitata.
- Consapevolezza del versioning. Le API cambiano. Tratta l'integrazione come codice che necessita di aggiornamenti, non come un cablaggio una tantum.
Cosa rende fragile un'integrazione
- Esportazioni CSV inviate via e-mail in giro per l'azienda e reimportate manualmente.
- Credenziali codificate a mano in posti che nessuno ricorda.
- Un unico lungo script che fa tutto senza logica di ritentativo.
- Fallimenti silenziosi, i dati smettono di fluire e nessuno se ne accorge per settimane.
- Sincronizzazione bidirezionale senza regole di conflitto chiare: quale parte vince quando entrambe sono cambiate?
Middleware o integrazione diretta?
Esistono tre approcci principali:
- Integrazione diretta: il sistema A comunica direttamente con il sistema B. È il più semplice per un solo collegamento, diventa caotico quando ce ne sono molti.
- Piattaforma di integrazione (iPaaS): uno strumento dedicato come una piattaforma di workflow gestisce i connettori. Ottimo per flussi semplici e comuni; può essere costoso e opaco per logiche complesse.
- Middleware su misura: un piccolo servizio interno che possiede la logica di integrazione, le traduzioni e la gestione degli errori. Spesso la scelta giusta quando la logica è specifica dell'azienda.
La risposta migliore dipende da quanti sistemi devono comunicare tra loro, quanta logica personalizzata è coinvolta e se vuoi le regole di business nell'interfaccia di un fornitore o in codice di tua proprietà.
Un esempio concreto di webhook
Supponi che una piattaforma di e-commerce debba notificare il tuo sistema di contabilità ogni volta che un ordine viene pagato. Invece di interrogarlo ogni minuto, lo shop chiama il tuo endpoint con un piccolo payload JSON:
{
"event": "order.paid",
"event_id": "evt_8f3c21a9",
"occurred_at": "2024-11-12T09:41:07Z",
"order": {
"id": "ORD-10427",
"total": 1499.00,
"currency": "PLN",
"customer_email": "k.nowak@example.com"
}
}Il servizio ricevente dovrebbe accettare la richiesta, verificare un header di firma, memorizzare l'event_id e restituire rapidamente 200. Il lavoro effettivo, come creare una fattura, avviene in un job in background. Se lo stesso evento arriva due volte, l'event_id memorizzato impedisce una fattura duplicata.
Regola pratica: i gestori di webhook dovrebbero confermare velocemente e svolgere il lavoro in modo asincrono. Tutto ciò che è lento o fragile, una chiamata a un'API di terzi, il rendering di un PDF, appartiene a una coda, non al gestore HTTP.
Gestire i ritentativi senza duplicati
Ogni integrazione affidabile necessita di una chiave di idempotenza. Un pattern minimo in pseudocodice:
async function handleOrderPaid(event) {
if (await seen(event.event_id)) return; // already processed
await markSeen(event.event_id);
await queue.enqueue('create-invoice', event.order);
}Errori comuni
- Integrare troppo presto. Se il processo non è stabile, l'integrazione cristallizzerà il disordine e renderà più difficile cambiarlo.
- Sincronizzazione bidirezionale per impostazione predefinita. Quella unidirezionale è più semplice e spesso sufficiente, passa alla bidirezionale solo se l'azienda ne ha davvero bisogno.
- Nessun monitoraggio. Un'integrazione senza avvisi è un fallimento silenzioso in attesa di accadere.
- Accoppiamento stretto. Le modifiche in un sistema non dovrebbero rompere tutti gli altri. Mantieni un livello di traduzione.
Un approccio realistico
- Disegna il flusso dei dati: quale sistema possiede quale campo e chi ne ha bisogno di copie.
- Inizia dal singolo flusso più doloroso e costruiscilo prima in modalità unidirezionale.
- Usa i webhook dove conta la bassa latenza, la sincronizzazione programmata dove non conta.
- Aggiungi il monitoraggio dal primo giorno, non dopo il primo guasto.
- Documenta credenziali, endpoint e proprietà, così l'integrazione sopravvive ai cambi di personale.
