Quando un sistema da cui un prodotto dipende non dispone di un'API pubblica, l'integrazione deve essere costruita sull'interfaccia che effettivamente espone — anche quando tale interfaccia è stata progettata per una persona, non per un programma. Su DinDin, una suite tecnologica connessa per ristoranti, quell'interfaccia era una casella di posta.
01Come leggere il lavoro
Il problema: due marketplace, nessuna API degli ordini
I clienti ristoranti di DinDin ricevono ordini da diversi canali — il proprio sito, il proprio punto vendita e marketplace di delivery di terze parti — e ciascuno di questi ordini deve raggiungere la stessa stampante da cucina, lo stesso reporting e lo stesso workflow operativo. Gli ordini Grubhub e DoorDash rappresentavano la lacuna: nessuno dei due marketplace esponeva l'API degli ordini di cui questo workflow aveva bisogno. Ciò che ciascun marketplace invia, in modo affidabile, è un'email HTML di conferma d'ordine alla casella di posta del ristorante — la stessa email che un manager leggerebbe manualmente.
02Come leggere il lavoro
Costruire l'integrazione sulla casella di posta
La pipeline si autentica su quella casella di posta condivisa e tratta ogni conferma in arrivo come superficie di integrazione: analizza l'email HTML di conferma d'ordine, associa il merchant a cui appartiene ed estrae l'ordine nel modello nativo degli ordini di DinDin. Da quel momento è indistinguibile da un ordine effettuato sul sito del ristorante stesso — confluisce sulla stessa stampante da cucina e sullo stesso reporting. Le Gmail API rappresentano un punto di riferimento ragionevole su come venga tipicamente costruita un'integrazione autenticata su casella di posta di questo tipo (vedere: le guide alle Gmail API, citate di seguito).
03Come leggere il lavoro
Deduplicazione: la parte che rende sicura la riesecuzione
Un'integrazione basata su email deve tollerare la riesecuzione — una connessione può interrompersi a metà di un fetch, o un messaggio può essere rielaborato. La pipeline deduplica in base al numero d'ordine proprio di ciascun marketplace anziché ricavare un'identità dal contenuto in testo libero, così la rielaborazione della stessa email di conferma non crea mai un secondo scontrino da cucina. Questa è la stessa disciplina delle richieste idempotenti documentata nella progettazione delle API di pagamento, dove un identificatore fornito dal client viene utilizzato appositamente affinché una richiesta ripetuta non possa addebitare o creare due volte (vedere: la documentazione di Stripe sulle richieste idempotenti, citata di seguito).
04Come leggere il lavoro
A cosa si generalizza questo principio
La lezione generale non riguarda solo i ristoranti o le email: quando un sistema non espone alcuna API, l'integrazione viene costruita sull'interfaccia più stabile che effettivamente espone — anche se pensata per una persona — e viene resa sicura per la riesecuzione con la stessa disciplina di deduplicazione che utilizzerebbe una vera integrazione API. In questo caso la casella di posta non è un espediente; trattata con la disciplina corretta, essa stessa è l'integrazione.
