GipoNext API

Italiano

English

Italiano

English

Appearance

Change management ​

Questa pagina descrive come vengono gestite le evoluzioni delle API nel tempo e come progettare un client resiliente.

Stabilità e compatibilità ​

Le API sono progettate per garantire stabilità verso le integrazioni esistenti:

  • non vengono rimossi campi esistenti;
  • non vengono modificati in modo breaking i campi già pubblicati;
  • non vengono cambiati i codici di stato HTTP per le stesse condizioni;
  • non vengono rinominati endpoint già in uso.

In questo modo, un'integrazione funzionante continua a funzionare anche con nuove versioni del backend.

Modifiche additive ​

Possono essere introdotte modifiche additive senza preavviso, ad esempio:

  • nuovi campi nelle risposte;
  • nuovi valori opzionali;
  • nuove proprietà in oggetti già esistenti;
  • nuovi endpoint.

Esempio concreto ​

Oggi una risposta paziente potrebbe avere questa struttura:

json
{
  "id": 123,
  "firstName": "Mario",
  "lastName": "Rossi",
  "fiscalCode": "RSSMRA80A01H501Z"
}

Domani la stessa risposta potrebbe includere un nuovo campo:

json
{
  "id": 123,
  "firstName": "Mario",
  "lastName": "Rossi",
  "fiscalCode": "RSSMRA80A01H501Z",
  "middleName": null
}

Questo non è un breaking change: il campo è stato aggiunto, nessun campo esistente è cambiato.

Come progettare un client resiliente ​

Per gestire correttamente le modifiche additive:

  • non assumere che la risposta contenga solo i campi oggi documentati — domani potrebbero essercene di più;
  • ignora in sicurezza i campi non riconosciuti — il tuo parser JSON non deve fallire se trova proprietà sconosciute;
  • valida solo i campi realmente necessari alla tua logica, non l'intera struttura della risposta;
  • non confrontare l'intera risposta JSON in modo rigido (es. con hash o uguaglianza esatta) per rilevare cambiamenti.

💡 Impostazione del deserializzatore

La maggior parte dei framework JSON moderni ignora le proprietà sconosciute per default (es. System.Text.Json in .NET, Jackson in Java, json in Python). Verifica che questa impostazione sia attiva nel tuo client.

Deprecazioni e notifiche ​

Quando un'API viene deprecata:

  1. La notifica viene inviata all'email dell'account che ha registrato l'applicazione OAuth.
  2. Viene concesso un periodo di transizione ragionevole prima della rimozione definitiva.
  3. La documentazione viene aggiornata per segnalare l'endpoint deprecato e indicare l'alternativa, se disponibile.

Per questo è consigliato usare come riferimento un account:

  • non personale (es. mailbox di team), oppure
  • comunque raggiungibile nel tempo anche in caso di cambi di persone o ruoli.

⚠️ Attenzione

Non monitorare le deprecazioni manualmente: assicurati che la mailbox associata all'applicazione OAuth sia letta regolarmente.

Prossimi passi ​