Linee guida sulla compatibilità con le versioni precedenti

Ogni richiesta dell'API YouTube Data può specificare la versione dell'API che YouTube deve utilizzare per gestire tale richiesta. Se una richiesta non specifica la versione API, YouTube utilizzerà la versione meno recente supportata dell'API per gestire tale richiesta. La versione meno recente supportata è attualmente 1. Tieni presente le seguenti caratteristiche dei numeri di versione dell'API:

  • YouTube potrebbe rilasciare aggiornamenti a una versione specifica dell'API per cui alla versione non è stato assegnato un nuovo numero di versione. Questi aggiornamenti compatibili con le versioni precedenti possono includere funzionalità API facoltative, correzioni di bug o entrambe.

  • Un incremento del numero di versione dell'API identifica una release che contiene modifiche incompatibili con le versioni precedenti dell'API.

Questo documento definisce le linee guida sulla compatibilità con le versioni precedenti degli aggiornamenti di una versione specifica dell'API, come il primo punto elencato sopra. Le linee guida cercano di distinguere tra i seguenti tipi di funzionalità dell'API:

  • Le linee guida identificano le funzionalità dell'API che potrebbero cambiare anche se non modifichi la versione dell'API da utilizzare per gestire le richieste API. Queste modifiche devono essere gestite dal tuo codice senza interruzioni. Ad esempio, se YouTube aggiunge nuovi tag XML alle risposte dell'API, il tuo codice deve ignorare tali tag.

  • Le linee guida definiscono anche la funzionalità dell'API che YouTube non intende modificare quando aggiorna una versione specifica dell'API. In altre parole, la funzionalità dovrebbe essere modificata solo se YouTube rilascia una nuova versione dell'API e il tuo codice non deve tentare di gestire questi tipi di modifiche.

Informazioni su questo documento

Il presente documento si articola nelle seguenti sezioni:

  • La sezione Richieste API definisce le linee guida relative alla compatibilità con le versioni precedenti relative alle intestazioni delle richieste HTTP, ai parametri delle richieste API, ai nomi degli elementi XML (come appaiono nelle richieste API) e alle richieste API formulate in modo errato.

  • La sezione Risposte API definisce le linee guida sulla compatibilità con le versioni precedenti relative ai nomi degli elementi XML (come appaiono nelle risposte API) e all'ordine di visualizzazione dei tag e degli attributi XML nelle risposte API.

  • La sezione Best practice illustra i consigli per l'integrazione dell'API di YouTube con l'applicazione client.

Richieste API

Funzionalità che non devono essere modificate

  • Parametri di richiesta esistenti.

  • Valori dei parametri esistenti per i parametri con valori enumerati o con il significato di tali valori.

  • I nomi degli elementi XML utilizzati nelle richieste POST (insert) o PUT (update) delle API.

  • L'insieme di intestazioni di richiesta HTTP necessarie per ciascun tipo di richiesta API. Questa norma indica che YouTube non intende aggiungere le intestazioni delle richieste HTTP richieste né modificare le intestazioni delle richieste facoltative esistenti.

  • Il comportamento di ignorare i parametri non supportati in una richiesta API, a meno che la richiesta non utilizzi il parametro strict, che indica a YouTube di rifiutare una richiesta API che contiene parametri di richiesta non validi.

Funzionalità che potrebbe cambiare

  • YouTube potrebbe aggiungere parametri di richiesta facoltativi.

  • YouTube potrebbe aggiungere nuovi valori per i parametri esistenti che hanno insiemi enumerati di valori,

  • YouTube può rifiutare qualsiasi richiesta in cui parametri validi contengano valori non validi. Di conseguenza, le richieste formate in modo errato che sono state accettate a causa di un'analisi eccessivamente permissiva potrebbero essere rifiutate se la logica di analisi è corretta.

  • YouTube potrebbe aggiungere intestazioni HTTP delle richieste facoltative.

  • YouTube può modificare le informazioni che conserva (archivia) quando inserisce o aggiorna una risorsa. Tuttavia, questa decisione non influirà o richiederebbe modifiche alla sintassi delle richieste API corrispondenti.

  • YouTube può modificare l'insieme di categorie sfogliabili o di categorie a cui possono essere assegnati i video appena caricati.

  • La funzionalità non documentata può essere rimossa o modificata in qualsiasi momento.

Risposte API

Funzionalità che non devono essere modificate

  • Nomi di tag XML esistenti.

  • Seguire la specifica Media RSS per determinare l'ordine degli elementi definiti nella specifica e visualizzati più volte in una voce del feed. Ad esempio, se una voce contiene più tag <media:thumbnail>, questi vengono ordinati in base all'importanza.

  • Il valore dell'attributo term del tag <category> che identifica il tipo di articolo descritto in un feed o in una voce del feed. All'interno del tag <feed> o <entry>, il tag <id> specifica la risorsa univoca identificata dalla voce, mentre un tag <category> identifica il tipo di risorsa descritta dalla voce. Per questo tag <category>, il valore dell'attributo schema è http://schemas.google.com/g/2005#kind e il valore dell'attributo termine indica se le voci del feed descrivono video, link a playlist, iscrizioni, contatti o un altro tipo di entità.

Funzionalità che potrebbe cambiare

  • YouTube potrebbe aggiungere nuovi tag XML alle risposte dell'API.

  • YouTube potrebbe aggiungere nuovi attributi ai tag XML esistenti.

  • I tag API esistenti possono essere ripetuti con valori diversi. Ad esempio, YouTube potrebbe aggiungere un nuovo tag <media:restriction> con un valore type diverso o un nuovo tag <media:credit> con scheme e role diversi.

  • L'ordine dei tag e degli attributi XML nella risposta dell'API potrebbe cambiare.

  • I tag secondari facoltativi possono essere rimossi dalle risposte dell'API.

  • La funzionalità non documentata può essere rimossa o modificata in qualsiasi momento.

Best practice

  • Utilizza il valore tag <id> per identificare una voce.

  • Usa il link self per recuperare una voce.

  • Utilizza il link edit per modificare o aggiornare una voce.

  • Utilizza il valore tag <yt:videoid> per una voce video per ottenere il valore utilizzato da YouTube per identificare in modo univoco il video. Non analizzare l'ID video da un link.

  • Utilizza gli URL identificati nei tag <link>, <content> e <gd:feedLink> per spostarti tra i feed. YouTube supporta un insieme limitato di URL che puoi creare in modo affidabile per recuperare feed specifici. A parte questi URL di feed, elencati di seguito, non devi costruirli poiché potrebbero smettere di funzionare inaspettatamente.

    • /feed/api/video/<videoid>
    • /feeds/api/users/default
    • /feeds/api/users/default/uploads
    • /feeds/api/users/default/favorites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/playlists
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (consulta la guida di riferimento per ulteriori informazioni)

  • Non provare ad analizzare gli identificatori numerici o alfanumerici degli URL in una risposta API. Le risposte dell'API includono tag specifici per gli identificatori che rimandano alle risorse sul sito web di YouTube, come gli ID video (<yt:videoid>) e i nomi utente (<name> e <media:credit>).)

  • Se invii una richiesta API per inserire informazioni (POST) o aggiornare (PUT), utilizza la risposta XML a questa richiesta per determinare quali valori di tag nella richiesta sono stati effettivamente memorizzati da YouTube. Come indicato nelle linee guida sulla compatibilità con le versioni precedenti delle richieste API, YouTube potrebbe modificare le informazioni che conserva (archivia) quando inserisce o aggiorna una risorsa, il che implica che alcuni tag nella richiesta potrebbero essere ignorati.

  • Quando recuperi un feed XML, memorizza i tag e gli attributi XML non riconosciuti relativi a una voce di feed se la tua applicazione consente all'utente di aggiornare la voce. Se l'utente aggiorna la risorsa, l'applicazione deve includere nella richiesta di aggiornamento eventuali tag e attributi non riconosciuti. In questo modo è possibile garantire che l'applicazione non elimini inavvertitamente informazioni relative a nuove funzionalità dell'API durante il processo di aggiornamento di una risorsa.

    L'esempio seguente illustra questa best practice:

    1. L'applicazione consente a un utente di aggiornare la descrizione di un video.
    2. L'applicazione recupera la voce video utilizzando l'API, ma non riconosce uno dei tag nella voce.
    3. L'utente modifica la descrizione del video.
    4. La tua richiesta deve inviare nuovamente una voce video completa all'API. La voce deve includere il tag non riconosciuto del passaggio 2, altrimenti tale valore potrebbe essere eliminato.

  • Verifica che un tag esista e contenga un valore non null prima di provare a visualizzare il valore del tag.

  • Come indicato in precedenza, YouTube potrebbe aggiungere nuovi valori per i tag o gli attributi esistenti con insiemi di valori enumerati. Di norma, il codice deve analizzare i valori degli elementi XML con insiemi enumerati di valori e quindi definire le azioni appropriate per tali valori. Questa pratica è consigliata anche se viene assegnato un solo valore possibile per l'elemento.

    Ad esempio, il tag <media:credit> identifica il proprietario di un video. L'unico valore documentato per l'attributo role del tag è uploader, che indica che il video è stato caricato da un partner di YouTube. Questa best practice prevede che l'applicazione debba confermare che il valore dell'attributo role del tag sia effettivamente uploader prima di identificare l'utente corrispondente come proprietario del video. Questa precauzione assicura che il tuo codice non identifichi in modo impreciso il proprietario di un video se YouTube aggiunge altri tipi di riconoscimenti, ad esempio il regista, per un video.

    • Se un tag ha un insieme enumerato di valori e non riconosci il valore di tale tag, devi ignorare l'intero <entry> all'interno del tag.

    • Ignora una voce del feed Iscrizioni se non riconosci il valore dell'attributo term per il tag <category> che ha un valore scheme per http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Tale tag identifica il tipo di abbonamento identificato dalla voce. Se la tua applicazione non riconosce il tipo di abbonamento, non deve mostrare informazioni su questa voce.

    • Se un altro attributo ha un insieme enumerato di valori e non riconosci il valore dell'attributo in questione, dovresti ignorare il tag in cui viene visualizzato l'attributo.

  • Il codice della tua applicazione dovrebbe ricevere un messaggio yt:error in qualsiasi momento. Nel caso in cui un'operazione dell'API non vada a buon fine, l'applicazione deve identificare l'errore e mostrare un messaggio significativo all'utente.

  • YouTube può aggiungere in qualsiasi momento nuove categorie per classificare i video. YouTube può anche aggiornare o ritirare le categorie esistenti. Puoi recuperare un file delle categorie attuali da http://gdata.youtube.com/schemas/2007/categories.cat.

    • Se la tua applicazione consente agli utenti di sfogliare video per categoria o di caricare video, recupera ogni settimana un file aggiornato delle categorie.

    • Se la tua applicazione consente agli utenti di sfogliare video per categoria, recupera anche un file delle categorie aggiornato se l'API restituisce un feed vuoto in risposta a una ricerca per categoria.

    • Se la tua applicazione consente agli utenti di caricare video, recupera anche un file delle categorie aggiornato prima di caricare un video e verifica che la categoria associata al video caricato sia ancora assegnabile. Per ulteriori informazioni, consulta la guida di riferimento. Tieni presente che se cerchi di assegnare un video a una categoria non assegnabile, l'API restituirà un messaggio di errore per il quale il valore del tag <code> è deprecated.

  • Utilizza i tag <link> in una risposta API per identificare i link di impaginazione per la pagina precedente e/o successiva di voci in un feed. Per ulteriori informazioni, consulta la sezione Panoramica dei risultati della guida di riferimento.