Controllo delle versioni

Questa guida spiega come l'API Merchant gestisce il controllo delle versioni, le release e il ciclo di vita delle sue diverse versioni.

Schema di controllo delle versioni

L'API Merchant utilizza una strategia di controllo delle versioni a livello di sotto-API. Ciò significa che ogni API, ad esempio Prodotti all'interno dell'API Merchant, avrà il proprio ciclo di vita della versione.

Formato e presentazione del controllo delle versioni

• Versioni secondarie stabili dell'API: se una sub-API è in una versione stabile, tutti i relativi metodi sono in una versione stabile. Una versione secondaria stabile dell'API è rappresentata come vX (ad esempio, v1, v2). Queste sono versioni principali pronte per la produzione.

• Versioni secondarie dell'API alpha: se una sub-API è in versione alpha, tutti i relativi metodi sono in versione alpha. Una versione secondaria alpha dell'API è rappresentata come vXalpha (ad esempio, v1alpha, v2alpha). Contengono funzionalità sperimentali di accesso in anteprima destinate a test e iterazioni rapide. Le versioni alpha non offrono alcuna garanzia di stabilità, non hanno una durata definita e possono essere modificate o ritirate con un preavviso di 30 giorni.

Modifiche versione

• Incrementi della versione principale (ad esempio, da v1 a v2): questi segnalano modifiche incompatibili con le versioni precedenti e che provocano errori, che richiedono l'intervento dello sviluppatore. Solo le modifiche che provocano un errore delle sub-API stabili avranno un nuovo numero di versione. Ad esempio, dalla versione 1 alla versione 2.

• Modifiche secondarie:le aggiunte o le correzioni compatibili con le versioni precedenti vengono presentate come modifiche alla versione principale esistente. Queste modifiche verranno descritte in dettaglio nelle note di rilascio della versione principale. Le aggiunte non distruttive a una sub-API verranno rilasciate sul canale alpha dell'ultima versione stabile o direttamente sull'ultima versione stabile.

Policy di ritiro

Ritiriamo periodicamente le versioni precedenti delle sub-API Merchant. Ci impegniamo a garantire un periodo di ritiro di 12 mesi per le versioni principali stabili (vX), a partire dall'annuncio ufficiale del ritiro.

Ad esempio, se ritiriamo la versione 1 della sub-API Products il 15 gennaio 2026, questa verrà ritirata non prima del 15 gennaio 2027. Dopo questa data, la versione precedente della sub-API non sarà più disponibile per l'utilizzo.

Versione e stato del ciclo di vita della sotto-API

La tabella seguente elenca le versioni più recenti di ogni API secondaria dell'API Merchant:

Best practice

• Controlla regolarmente le note di rilascio e gli ultimi aggiornamenti per nuove versioni, aggiornamenti principali, miglioramenti e annunci relativi a lanci e ritiri di API secondarie.
• Se una sub-API ha due o più versioni stabili, ti consigliamo di utilizzare sempre l'ultima versione.
• Progetta la tua applicazione in modo che gestisca correttamente vari errori delle API secondarie, inclusi problemi di rete, limiti di frequenza e i nuovi codici o messaggi di errore che potrebbero essere introdotti con le versioni più recenti delle API secondarie.
• Non aspettare che una versione secondaria dell'API stia per essere ritirata per iniziare a pianificare l'upgrade. Inizia a valutare e testare le nuove versioni non appena sono disponibili.
• Per richieste di funzionalità o dubbi sulla roadmap di una sub-API, contattaci per domande o feedback. Per informazioni su come contattare il team dell'API Merchant per ricevere assistenza tecnica, consulta Ricevere assistenza per l'API Merchant.