Insieme a X API v2, abbiamo introdotto una nuova strategia di versionamento che consente agli sviluppatori di capire meglio quando aspettarsi modifiche alle API pubbliche di X e quando sarà necessario effettuare la migrazione a nuove versioni.
Gli sviluppatori saranno informati di deprecazioni, ritiri, modifiche e aggiunte alla X API tramite i nostri canali di comunicazione, così da poter pianificare adeguatamente l’inserimento di tali modifiche nella loro roadmap di sviluppo. Tutte le modifiche all’API saranno riportate nel changelog.
Attualmente la X API dispone di tre versioni. Consigliamo vivamente di utilizzare X API v2 quando si pianifica l’integrazione, a meno che in v2 non siano ancora disponibili funzionalità necessarie per il vostro caso d’uso.
Per ulteriori informazioni su ciascuna versione, visitate le seguenti pagine:
- X API v2
- Gnip 2.0 (Enterprise)
Strategia di versioning
Il versioning della X API è rappresentato da numeri di versione dichiarati nel percorso della route degli endpoint:
https://api.x.com/2/tweets
Puntiamo a rilasciare nuove major release della X API quando necessario, ma non più frequentemente di ogni 12 mesi. Una major release verrà pubblicata quando nell’API vengono introdotte modifiche incompatibili con le versioni precedenti (breaking change). Al lancio di una nuova major release pubblicheremo guide di migrazione per aiutare gli sviluppatori a passare alla nuova versione.
Una breaking change richiede agli sviluppatori di modificare il codice per mantenere la funzionalità esistente nella loro App. Le modifiche non interruttive saranno additive e verranno distribuite alla versione più recente quando pronte, senza richiedere interventi da parte dello sviluppatore a meno che non si desideri sfruttare le nuove funzionalità.
Se una breaking change deve essere distribuita a metà ciclo (per motivi di sicurezza o privacy), tale modifica verrà applicata alla versione più recente.
Modifiche che interrompono la compatibilità
Queste modifiche richiedono agli sviluppatori di aggiornare il codice per mantenere la funzionalità esistente della loro applicazione.
- Aggiunta di un nuovo parametro obbligatorio
- Rimozione di un endpoint esistente
- Rimozione di qualsiasi campo nella risposta (obbligatorio o facoltativo)
- Rimozione di un parametro query
- Ristrutturazione del formato di input o output (ad esempio, trasformare un campo di primo livello in un sotto-campo o spostare gli errori in linea)
- Modifica del nome o del tipo di dati di un parametro di input esistente o di un valore di output
- Modifica del nome di un campo
- Modifica del nome della risorsa
- Modifica di un codice di risposta
- Modifica dei tipi di errore
- Modifiche agli scope di autorizzazione esistenti
Modifiche retrocompatibili
- Introduzione di un nuovo endpoint
- Introduzione di un nuovo parametro opzionale
- Introduzione di un nuovo campo nella risposta
- Modifica del testo dei messaggi di errore
- Disponibilità di nuovi scope
- Impostazione a null dei fields (impostare il valore di un campo a null per motivi di privacy/sicurezza, in alternativa alla sua completa rimozione)
Deprecation e ritiro
Prima di tutto, ecco come definiamo “deprecation” e “ritiro” per la X API:
- Deprecation: La funzionalità non è più supportata dal team. Non verranno rilasciati nuovi sviluppi per quella funzionalità e, in caso di bug o problemi, le probabilità che venga implementata una correzione sono estremamente basse.
- Ritiro: La funzionalità non sarà più accessibile.
Nella maggior parte dei casi, non appena viene rilasciata una nuova versione, la versione precedente viene contrassegnata come deprecata. Le versioni restano in stato di deprecazione per un certo periodo, al termine del quale vengono ritirate.
Ti invitiamo a rimanere aggiornato per saperne di più sulle future deprecazioni e sui ritiri.