Ciclo di vita

L’API è costruita attorno a un unico endpoint GraphQL in continua evoluzione. Questa architettura garantisce che nuove funzionalità e miglioramenti delle prestazioni vengano rilasciati in modo continuo, senza richiedere la migrazione tra versioni dell’API.

Questa pagina descrive i diversi livelli di stabilità dell’API, le garanzie di stabilità dell’API stabile, i tipi di modifiche (breaking e non breaking) e come vengono gestite le deprecazioni. Per le funzionalità attualmente in anteprima, consulta le funzionalità sperimentali.

Ciclo di vita delle funzionalità

Ogni funzionalità si trova a uno di tre livelli di stabilità: alpha, beta o stabile. La maggior parte delle funzionalità li attraversa in ordine e le funzionalità stabili possono essere ritirate solo tramite un processo di deprecazione.

[ ALPHA ] ──> [ BETA ] ──> [ STABLE ] ──> [ DEPRECATED ] ──> [ REMOVED ] Opt-in        Enabled                      12+ month               by default                   notice window

API stabile

Le funzionalità stabili rappresentano il nucleo dell’API pronto per la produzione. Le modifiche sono classificate in due categorie, non breaking e breaking.

Modifiche non breaking

Aggiunte retrocompatibili che non interrompono le integrazioni esistenti. Vengono rilasciate in modo continuo, senza preavviso né deprecazione.

Le modifiche non breaking includono:

• Aggiungere una nuova query, mutation o subscription.
• Aggiungere un nuovo argomento di input facoltativo a un’operazione esistente.
• Aggiungere un nuovo argomento con un valore predefinito che mantiene il comportamento esistente.
• Aggiungere un nuovo campo all’output di un’operazione esistente.
• Rendere facoltativo un argomento di input obbligatorio.
• Aggiungere un nuovo valore a un tipo enum esistente.

Costruire pensando alle modifiche non breaking

Le modifiche non breaking possono comunque influire sui client che fanno ipotesi troppo rigide. Per mantenere le integrazioni resilienti:

• Evita una deserializzazione rigida degli oggetti che fallisce quando compaiono proprietà aggiuntive nei payload.
• I tipi enum di GraphQL non sono esaustivi e si espandono nel tempo. Implementa sempre un caso predefinito di fallback nella logica del client.
• Ispeziona i valori extensions.exception.code degli errori anziché confrontarli con stringhe di errore leggibili.

Modifiche breaking e deprecazioni

Una modifica breaking potrebbe interrompere le integrazioni attive esistenti. Di conseguenza, qualsiasi modifica breaking deve prima passare attraverso un processo di deprecazione di 12 mesi.

Le modifiche breaking includono:

• Rimuovere o rinominare una query, mutation, subscription, campo o argomento di input esistente.
• Rimuovere o rinominare valori enum.
• Cambiare il tipo di dati di un campo o di un argomento di input esistente.
• Aggiungere un nuovo argomento di input obbligatorio.
• Rendere obbligatorio un argomento di input facoltativo.
• Alterare la logica di business o il comportamento di un campo esistente.
• Cambiare un campo di output da non nullable (!) a nullable.
• Cambiare il valore predefinito di un argomento di input o di un campo.
• Cambiare i valori predefiniti della paginazione, le dimensioni massime delle pagine o l’ordinamento documentato.

Cronologia della deprecazione

Quando una modifica breaking richiede di rimuovere o sostituire una funzionalità stabile, segue una rigorosa cronologia in tre fasi:

1. Annuncio della deprecazioneLa funzionalità viene contrassegnata con la direttiva @deprecated nello schema GraphQL. Se applicabile, viene fornito un percorso di migrazione. La deprecazione e la rispettiva data di rimozione vengono annunciate contemporaneamente attraverso tre canali di monitoraggio.
2. Periodo di preavviso attivo (mesi 1–12)La funzionalità deprecata rimane pienamente operativa. Se è previsto un percorso di migrazione, gli integratori devono aggiornare le proprie applicazioni e adottare i nuovi campi durante questo periodo di 12 mesi.
3. Rimozione definitivaAlla data di rimozione, la funzionalità viene rimossa in modo permanente. Qualsiasi richiesta successiva che usi la funzionalità fallirà la validazione dello schema con un errore GraphQL.

Monitorare le deprecazioni

Individua e monitora i prossimi ritiri attraverso tre canali:

• Ispeziona le direttive @deprecated(reason: "...") nei tuoi strumenti per lo schema.
• Consulta le date di dismissione e le guide alla migrazione nella sezione legacy dell’API o nel portale delle deprecazioni.
• Monitora gli avvisi DEPRECATED_FEATURE restituiti direttamente nelle risposte dell’API.

{  "data": {    "station": {      "id": "5e8c22366f9c5f23ab0eff39",      "amenityList": [        {          "name": "Coffee Shop",          "foursquareUrl": "https://foursquare.com/v/example"        }      ]    }  },  "extensions": {    "warnings": [      {        "code": "DEPRECATED_FEATURE",        "path": ["amenityList", "foursquareUrl"],        "message": "This feature is deprecated and will be removed. To prevent errors and service disruptions, migrate to the recommended alternative before the scheduled removal date. Visit https://developers.chargetrip.com/deprecations for more information."      }    ]  }}