Versioning

Tutta l’API pubblica vive sotto il prefisso /public/v1, esplicito in ogni rotta.

Cosa promettiamo all’interno di /public/v1

Finché un’integrazione esiste sotto /public/v1, mai:

• viene rimosso un campo da una risposta,
• viene cambiato il tipo di un campo esistente,
• viene irrigidita una validazione al punto che un corpo prima valido smetta di esserlo.

Aggiungere un campo nuovo a una risposta, un endpoint nuovo, o un nuovo parametro di filtro opzionale è compatibile — la tua integrazione deve ignorare i campi che non riconosce, mai fallire per la loro presenza.

Cosa succede con un cambiamento incompatibile

Un cambiamento che romperebbe quanto sopra nasce in un nuovo router, /public/v2, mai modificando /public/v1 sul posto. /public/v1 continua a funzionare per almeno 6 mesi dopo la pubblicazione di /public/v2 — durante quella finestra, ogni risposta di un endpoint segnato per il ritiro porta gli header standard (RFC 8594):

Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT

Nessun endpoint è deprecato oggi — se lo fosse, questa pagina lo elencherebbe esplicitamente, con la sua data di ritiro e il suo sostituto sotto /public/v2.