Vai al contenuto

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

01

Come funziona il versioning

Un solo numero nel percorso, modificato solo in caso di modifica incompatibile.

Versione bloccata di richiesta e risposta

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.

02

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.

Formato dell’header Deprecation

Valori di header illustrativi, non un annuncio di ritiro della versione.

03

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