Immagina che un sito di ordinazione invii un nuovo ordine a un sistema gestionale. Il gestionale lo salva, ma la conferma non raggiunge mai il sito. Il sito deve riprovare? Potrebbe creare un secondo ordine? Questa situazione esemplificativa mostra perché un contratto API conta per le attività aziendali. Descrive il comportamento atteso da entrambe le parti, compresi i casi che una dimostrazione riuscita potrebbe non rivelare mai.
In questa pagina
Parti dal percorso aziendale e dalla responsabilità sui dati
Mappa un’interazione dall’azione dell’utente al suo esito confermato. Nell’esempio dell’ordine, individua chi crea il riferimento, quale sistema decide se accettarlo e dove il cliente ne controlla lo stato. Distingui la ricezione di una richiesta dall’accettazione di un ordine: possono essere eventi diversi. Decidi anche quale sistema può modificare ciascuna informazione. Se entrambi possono cambiare un indirizzo di consegna, il contratto deve prevedere una regola per gli aggiornamenti, anziché presumere che l’ultima schermata contenga il valore autorevole.
- Indica il responsabile delle informazioni su ordini, clienti e stati.
- Specifica quale risultato l’utente deve vedere subito.
- Individua gli aggiornamenti successivi che il sistema ricevente deve inviare.
Rendi concrete le definizioni dei campi
Per ogni messaggio, documenta informazioni obbligatorie, valori consentiti e significato dei dati mancanti. Un prezzo richiede una valuta e un’interpretazione chiara; un timestamp richiede una convenzione concordata sul fuso orario. Usa un ordine di esempio realistico per discutere queste regole. Chiedi se «annullato» descrive l’intero ordine o un singolo articolo e se un indirizzo vuoto significa sconosciuto o rimosso intenzionalmente. Descrivi quali record ogni chiamante può leggere o modificare. Queste decisioni incidono sia sulla specifica sia sull’esperienza dell’applicazione: far coincidere i nomi dei campi non basta a risolverle.
Specifica richieste ripetute ed errori utili
Per l’ordine dell’esempio, una possibile regola è questa: entro un periodo di conservazione concordato, inviare nuovamente lo stesso identificatore di richiesta con dettagli identici restituisce il riferimento dell’ordine esistente. Riutilizzare quell’identificatore con dati diversi genera un conflitto che il chiamante deve risolvere. Definisci esplicitamente l’ambito dell’identificatore e il suo periodo di conservazione. Poi distingui gli errori da correggere dai guasti temporanei. Un timeout da solo non stabilisce se l’ordine è stato salvato, quindi il chiamante deve poter verificare l’esito prima di decidere il passo successivo.
- Indirizzo di consegna mancante: restituisci una spiegazione riferita al campo; correggi la richiesta prima di inviarla di nuovo.
- Esito incerto: cerca l’identificatore della richiesta e riconcilia lo stato registrato.
- Guasto temporaneo del servizio: segui la politica di nuovi tentativi concordata; evita di creare una nuova identità dell’ordine a ogni tentativo.
Concorda come testare e modificare il contratto
Chiedi a entrambi i team di esaminare un ordine riuscito, una richiesta ripetuta, un indirizzo non valido e una conferma interrotta. Verifica che si aspettino lo stesso risultato in ogni caso. Conserva questi esempi insieme alla specifica e usali quando l’integrazione cambia. Indica chi è responsabile dell’approvazione delle modifiche, della comunicazione ai team collegati e dell’analisi degli incidenti. Il passaggio di consegne dovrebbe spiegare come l’assistenza può tracciare una richiesta senza esporre informazioni superflue sul cliente e come verrà introdotta una modifica incompatibile per i consumatori esistenti dell’API.