Versioning dei contratti

Versioning dei contratti

Quando l'API si sviluppa attivamente, è importante mantenere la coesistenza tra le versioni ed evitare situazioni in cui una sola modifica rompe decine di integrazioni client. Abbiamo implementato una versioning dei contratti completa che consente di controllare le modifiche e aggiornare l'API senza rischi per gli utenti.

Questo è fondamentale nell'architettura a microservizi, nelle integrazioni B2B e nei prodotti API aperti, in cui i clienti utilizzano versioni diverse delle interfacce.

Cosa stiamo versionando

Oggetto	Descrizione
specifiche	Memorizzare ogni versione della documentazione e del contratto
Endpoint's	Aggiungi versioni all'URL ('/v1/', '/v2/'), salviamo backward compatibility
Contratti	Fissa condizioni di interazione tra client e server
Modelli dati	Controllo delle modifiche alla struttura di richiesta e risposta

Come implementiamo

Supporto di più API parallele
Specifica esplicitamente la versione in URL, intestazioni o parametri
Automatizza ogni versione dei contratti (Pact, Postman, Jest, Dredd)
Versioning delle specifiche su Git o su CHI/CD
Documentazione e changelog per i clienti a ogni modifica

Vantaggi

Garanzia di stabilità delle integrazioni
Possibilità di rilasciare nuove fitte senza il rischio di «rompere» i clienti
Migrazione semplificata tra le versioni
Una storia chiara di cambiamenti e controllo dei contratti
Trasparenza per i comandi di sviluppo esterni e interni

Dove è particolarmente importante

Architettura a microservizi con più dipendenze
Piattaforme API pubbliche o B2B
Sistemi finanziari e di pagamento con contratti a lungo termine
Applicazioni mobili che dipendono da un'API stabile

La versionalizzazione dei contratti è la base della prevedibilità e della fiducia nell'API. Implementiamo processi che consentono di modificare e sviluppare l'API senza soffrire, mantenendo compatibilità e trasparenza per tutte le parti.