Risposta.

Storicamente, la descrizione delle interfacce tra sistemi era compito di architetti e integratori, spesso riducendosi a scambi di email con strutture dati. Nell'era dell'SOA e ancor di più nell'architettura a microservizi, il ruolo dell'analista di sistema nella formalizzazione e nel supporto dei contratti di integrazione è aumentato drasticamente.

Problema

Una descrizione errata, incompleta o obsoleta delle interfacce API porta a: incompatibilità dei servizi, aumento del numero di bug, impossibilità di apportare modifiche senza causare interruzioni a catena del funzionamento dell'intero sistema. Nei progetti multiservizi, il numero di punti di integrazione raggiunge decine e centinaia.

Soluzione

L'analista di sistema applica pratiche moderne:

formalizzazione dei contratti tramite strumenti come OpenAPI/Swagger per REST, protocolli gRPC, WSDL/XSD per SOAP;
descrizione di scenari tipici di chiamata e situazioni di errore;
sviluppo di schemi di eventi (modello event-driven) per scambi in tempo reale;
mantenimento di documentazione aggiornata e autogenerazione di contratti;
approvazione delle modifiche con i proprietari di tutti i servizi coinvolti.

Un elemento importante è la gestione della corretta versioning e tracciamento delle modifiche ai contratti, così come l'integrazione di casi di test per la validazione delle interazioni.

Caratteristiche chiave:

Utilizzo di standard leggibili dalle macchine (OpenAPI/YAML).
Considerazione di tutti gli scenari di utilizzo e errori.
Comunicazione regolamentata tra i team di diversi servizi.

Domande trabocchetto.

L'analista deve raccogliere requisiti per l'API solo dai clienti e sviluppatori interni?

No, è importante coinvolgere tutti i team di integrazione, considerando le esigenze dei partner esterni, per evitare lacune o incompatibilità.

È possibile documentare l'API solo al momento della consegna del sistema?

No, la specifica dell'API deve essere formulata e approvata prima dell'implementazione, altrimenti la retrocompatibilità sarà compromessa a ogni fase.

La specifica OpenAPI è di per sé una documentazione sufficiente per tutti i casi di scambio?

No, OpenAPI descrive le strutture, ma gli scenari di interazione (ad esempio, ordine di chiamata, sequenza di eventi, errori di business) devono essere descritti dall'analista nella documentazione utente.

Errori tipici e anti-pattern

Fornire documenti obsoleti o descrizioni "umane" invece di specifiche.
Non descrivere la gestione degli errori, scenari impliciti.
Mancanza di controllo delle versioni e tracciamento delle modifiche.

Esempio dalla vita reale

Caso negativo: Il sistema di logistica si è integrato con trasportatori esterni. Il contratto è stato descritto solo "a parole". Dopo l'uscita delle modifiche, ci sono state interruzioni massicce dell'integrazione e ritardi.

Punti di forza:

Minimi costi di avvio

Punti deboli:

Interruzioni di massa
Modifiche urgenti
Reputazione negativa

Caso positivo: L'analista ha redatto un OpenAPI con esempi di errori/scenari di successo, ha concordato la versioning, ha raccolto feedback da tutti i team.