Quando l'API si sviluppa attivamente, è importante mantenere la compatibilità tra le versioni ed evitare che una sola modifica rompa decine di integrazioni client. Implementiamo una versione completa dei contratti per 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 |
|---|---|
| OpenAPI specifiche | Memorizza ogni versione della documentazione e del contratto |
| Endpoint'ы | Aggiungi versioni all'URL ('/v1/', '/v2/'), salviamo backward compatibility |
| Contratti (Pact, Dredd) | Fissazione delle condizioni di interazione tra client e server |
| Modelli di 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.