Linee guida sulla compatibilità con le versioni precedenti

Ogni richiesta all'API YouTube Data può specificare la versione dell'API che YouTube deve utilizzare per gestire la richiesta. Se una richiesta non specifica una versione dell'API, YouTube utilizzerà la versione più vecchia supportata dell'API per gestirla. Al momento, la versione più vecchia supportata è 1. Tieni presente le seguenti caratteristiche dei numeri di versione dell'API:

  • YouTube potrebbe rilasciare aggiornamenti a una versione API specifica a cui 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 per la compatibilità con le versioni precedenti per gli aggiornamenti a una versione API specifica, il primo elemento elencato sopra. Le linee guida mirano a 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 dell'API. Il codice dovrebbe gestire queste modifiche senza interruzioni. Ad esempio, se YouTube aggiunge nuovi tag XML alle risposte dell'API, il codice deve ignorarli.

  • Le linee guida definiscono anche le funzionalità dell'API che YouTube non intende modificare quando aggiorna una versione specifica dell'API. In altre parole, dovresti aspettarti che la funzionalità cambi 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 linee guida di 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 con formato non corretto.

  • La sezione Risposte dell'API definisce le linee guida per la compatibilità con le versioni precedenti relative ai nomi degli elementi XML (come appaiono nelle risposte dell'API) e all'ordine in cui i tag e gli attributi XML appaiono nelle risposte dell'API.

  • La sezione Best practice illustra i consigli per integrare l'API YouTube con la tua applicazione client.

Richieste API

Funzionalità che non devono cambiare

  • Parametri di richiesta esistenti.

  • Valori parametro esistenti per i parametri che hanno valori enumerati o i significati di questi valori parametro.

  • I nomi degli elementi XML utilizzati nelle richieste POST (inserimento) o PUT (aggiornamento) dell'API.

  • L'insieme di intestazioni di richiesta HTTP richieste per ogni tipo di richiesta API. Queste linee guida indicano che YouTube non intende aggiungere intestazioni di richiesta HTTP obbligatorie o modificare le intestazioni di richiesta facoltative esistenti in modo che diventino obbligatorie.

  • 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 contenente parametri di richiesta non validi.

Funzionalità che potrebbero 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 i parametri validi contengono valori non validi. Di conseguenza, le richieste con formattazione non corretta che sono state accettate a causa di un'analisi troppo permissiva potrebbero essere rifiutate se la logica di analisi viene corretta.

  • YouTube potrebbe aggiungere intestazioni facoltative delle richieste HTTP.

  • YouTube può modificare le informazioni che conserva (memorizza) quando inserisce o aggiorna una risorsa. Tuttavia, una decisione del genere non influirebbe né richiederebbe modifiche alla sintassi delle richieste API corrispondenti.

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

  • Le funzionalità non documentate possono essere rimosse o modificate in qualsiasi momento.

Risposte API

Funzionalità che non devono cambiare

  • Nomi dei tag XML esistenti.

  • Seguire la specifica RSS Media per determinare l'ordine degli elementi definiti in quella specifica e che appaiono 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 elemento 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 e un tag <category> identifica il tipo di risorsa descritto dalla voce. Per questo tag <category>, il valore dell'attributo scheme è http://schemas.google.com/g/2005#kind e il valore dell'attributo term indica se le voci del feed descrivono video, link a playlist, iscrizioni, contatti o un altro tipo di entità.

Funzionalità che potrebbero 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 potrebbero essere rimossi dalle risposte dell'API.

  • Le funzionalità non documentate possono essere rimosse o modificate in qualsiasi momento.

Best practice

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

  • Utilizza il link self per recuperare una voce.

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

  • Utilizza il valore del tag <yt:videoid> per una voce del 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 gli URL dei feed elencati di seguito, non dovresti creare i tuoi URL dei feed, poiché potrebbero smettere di funzionare in modo imprevisto.

    • /feeds/api/videos/<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 (per ulteriori informazioni, consulta la guida di riferimento)

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

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

  • Quando recuperi un feed XML, memorizza i tag e gli attributi XML non riconosciuti relativi a una voce del feed se la tua applicazione consente all'utente di aggiornare la voce. Se l'utente aggiorna la risorsa, la tua applicazione deve includere eventuali tag e attributi non riconosciuti nella richiesta di aggiornamento. Questa pratica garantisce che l'applicazione non elimini inavvertitamente le informazioni relative alle nuove funzionalità dell'API durante l'aggiornamento di una risorsa.

    L'esempio seguente illustra questa best practice:

    1. La tua applicazione consente a un utente di aggiornare la descrizione di un video.
    2. L'applicazione recupera la voce del video utilizzando l'API, ma non riconosce uno dei tag al suo interno.
    3. L'utente modifica la descrizione del video.
    4. La tua applicazione deve inviare un record video completo all'API. La voce deve includere il tag non riconosciuto del passaggio 2; in caso contrario, il valore potrebbe essere eliminato.

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

  • Come indicato sopra, YouTube potrebbe aggiungere nuovi valori per tag o attributi esistenti che hanno insiemi enumerati di valori. In genere, il codice deve analizzare i valori degli elementi XML che hanno insiemi enumerati di valori e poi definire le azioni appropriate per questi valori. Questa pratica è consigliata anche se per l'elemento è elencato un solo valore possibile.

    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 la tua 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 ti consente di assicurarti 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.

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

    • Ignora una voce del feed di iscrizioni se non riconosci il valore dell'attributo term per il tag <category> che ha un valore dell'attributo scheme pari a http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Questo particolare tag identifica il tipo di abbonamento identificato dalla voce. Se l'applicazione non riconosce il tipo di abbonamento, non deve mostrare informazioni sulla voce.

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

  • Il codice dell'applicazione deve aspettarsi un messaggio yt:error in qualsiasi momento. Se un'operazione dell'API non va a buon fine, l'applicazione deve identificare l'errore e mostrare un messaggio significativo all'utente.

  • YouTube può aggiungere nuove categorie per la classificazione dei video in qualsiasi momento. YouTube può anche aggiornare o ritirare le categorie esistenti. Puoi recuperare un file delle categorie attuali all'indirizzo http://gdata.youtube.com/schemas/2007/categories.cat.

    • Se la tua applicazione consente agli utenti di sfogliare i video per categoria o di caricarli, recupera un file delle categorie aggiornato su base settimanale.

    • Se la tua applicazione consente agli utenti di sfogliare i 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 provi ad 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 dell'API per identificare i link di paginazione per la pagina precedente e/o successiva delle voci in un feed. Per ulteriori informazioni, consulta la sezione Sfogliare i risultati della guida di riferimento.