Passa al contenuto principale

Versionamento dell'API

L'API pubblica usa versioni datate, lo stesso schema di Shopify, così la versione su cui sviluppi non cambia sotto i tuoi piedi. Le versioni datate sono il confine grossolano per le modifiche non retrocompatibili; all'interno di una versione lo schema continua a evolvere solo per aggiunta.

Nomi delle versioni​

Una versione si chiama YYYY-MM, dove il mese è l'inizio di un trimestre: 2026-01, 2026-04, 2026-07, 2026-10. Una nuova versione datata viene rilasciata solo quando c'è una modifica non retrocompatibile: i trimestri senza modifiche di questo tipo vengono saltati, perciò le versioni sono relativamente rare.

Esiste anche una versione unstable che segue lo stato più avanzato dello sviluppo e permette di vedere in anteprima le modifiche prima di un rilascio stabile. Non costruirci sopra integrazioni di produzione.

Selezionare una versione​

Due modi, in ordine di precedenza:

  1. Percorso nell'URL (consigliato): metti la versione nell'endpoint — …/backend/<subdomain>/api/2026-07/graphql. È esplicito, adatto alla cache e facile da copiare e incollare.
  2. Header della richiesta: invia X-Api-Version: 2026-07 all'endpoint semplice …/backend/<subdomain>/graphql.

Se ometti la versione — o ne indichi una sconosciuta o già oltre la data di dismissione — la richiesta viene servita dalla versione più vecchia ancora supportata, mai dalla più recente. Non vieni mai aggiornato in silenzio su una modifica non retrocompatibile. Fissa una versione esplicitamente per ogni integrazione che intendi mantenere.

Ogni risposta indica la versione che l'ha servita in un header X-Api-Version, così sai sempre quale contratto ha risposto e puoi rilevare uno scostamento se ti sei affidato al comportamento predefinito.

Periodo di supporto​

Ogni versione stabile è supportata per almeno 12 mesi, con almeno 9 mesi di sovrapposizione con la successiva. In pratica due o tre versioni sono attive in ogni momento, il che lascia una finestra comoda per migrare. La data di dismissione di una versione viene pubblicata il giorno stesso in cui esce.

Che cosa conta come modifica non retrocompatibile​

All'interno di una stessa versione possiamo apportare modifiche additive, e il tuo client deve tollerarle:

  • aggiungere un nuovo tipo, query o mutazione;
  • aggiungere un argomento facoltativo a un campo esistente;
  • aggiungere un campo a un tipo oggetto;
  • aggiungere un valore a un enum (quindi non dare mai per scontato che un enum sia chiuso).

Una nuova versione datata è riservata alle modifiche davvero non retrocompatibili: rimuovere o rinominare un campo o un tipo, irrigidire la nullabilità, oppure cambiare il significato di un argomento o di un valore predefinito. Queste non avvengono mai all'interno di una versione esistente: la versione che hai fissato mantiene il proprio comportamento fino alla data di dismissione.

Deprecazioni​

Le deprecazioni vengono segnalate in due modi, così le scopri prima che qualcosa si rompa:

  • Nello schema. Un campo in via di ritiro è contrassegnato con @deprecated e una motivazione che ne indica il sostituto. L'introspezione e il GraphQL Playground lo mostrano automaticamente a ogni client.
  • Nella risposta. Quando una richiesta risolve davvero un campo deprecato, la risposta porta l'header X-Api-Deprecated-Reason (e una corrispondente voce extensions.deprecations) che nomina le deprecazioni specifiche toccate: una deprecazione compare quindi nei tuoi log appena la incontri, senza doverla cercare.

Un campo deprecato viene mantenuto per un periodo minimo pubblicato prima di essere rimosso in una versione datata successiva.