API ecentic: gestione delle versioni.
La versione è nel percorso. Un'integrazione che fissa una versione mantiene il contratto per cui è stata sviluppata e non lo perde mai senza preavviso.
Versioning nel percorso URL · Preavviso di 180 giorni · Header Deprecation e Sunset
Come funziona il versioning
Un solo numero nel percorso, modificato solo in caso di modifica incompatibile.
La versione corrente è v1, disponibile su /api/v1. Ogni risposta riporta anche la versione in un header API-Version, così un client che segue un redirect o un link può confermare con cosa sta effettivamente comunicando.
Aggiungi alla stessa versione
Le modifiche additive vengono introdotte all'interno della stessa versione: nuovi endpoint, nuovi campi opzionali nelle richieste, nuovi campi in una risposta esistente. Tratta i campi di risposta sconosciuti come compatibilità futura, non come errori.
Avvia un nuovo percorso di versione
Una modifica che rimuove un campo, lo rinomina, restringe un tipo o cambia il significato di un valore esistente è una breaking change e viene pubblicata come nuovo percorso di versione accanto a quello precedente — mai al suo posto.
Deprecazione e sunset
Due header standard e una finestra temporale sufficiente per intervenire.
Seleziona un header per vedere cosa comunica al tuo client.
Deprecazione annunciata
Una versione è deprecata
Ogni risposta di una versione deprecata include questo header. Annuncia la deprecazione tramite RFC 9745.
Data di rimozione annunciata
È stata fissata una data di rimozione
Le risposte includono anche questo header una volta fissata una data di rimozione. RFC 8594 definisce la data in cui la versione smette di rispondere.
Versione sostitutiva collegata
La versione sostitutiva è identificata
Accanto alla data di rimozione, un Link con rel="successor-version" indirizza il tuo client alla versione sostitutiva.
Valori di header illustrativi, non un annuncio di ritiro della versione.
Cosa non è versionato
I documenti di discovery seguono invece la versione del rispettivo protocollo.
I documenti di discovery .well-known sono versionati in base al protocollo che implementano, non alla versione dell’API ecentic: il profilo UCP include una versione UCP, la server card MCP include una versione del protocollo e così via. Leggere la versione all’interno del documento è sempre corretto; dedurla dalla versione dell’API ecentic non lo è.
- Contratto API di ecentic
- /api/v1
- API-Version: 1
- Contratto del protocollo Discovery
- .well-known
- Leggi la versione nel documento