Diretrizes de compatibilidade com versões anteriores

Cada solicitação à API de dados do YouTube pode especificar a versão da API que o YouTube deve usar para manipular a solicitação. Se uma solicitação não especificar a versão da API, o YouTube usará a versão suportada mais antiga da API para manipular a solicitação. Atualmente, a versão suportada mais antiga é 1. Observe as seguintes características nos números de versão da API:

  • O YouTube pode lançar atualizações para uma versão específica da API e essa atualização não receber um novo número de versão. Essas atualizações compatíveis com versões anteriores podem incluir recursos e/ou correções de bug opcionais da API.

  • Um aumento no número de versão da API identifica uma versão que contém alterações incompatíveis com as versões anteriores da API.

Este documento define diretrizes de compatibilidade com versões anteriores para atualizações de uma versão específica da API, o primeiro item listado acima. As diretrizes buscam distinguir os seguintes tipos de funcionalidade da API:

  • As diretrizes identificam funcionalidades da API que poderão ser alteradas mesmo se você não modificar a versão da API que deverá ser usada para manipular suas solicitações à API. O seu código deve manipular essas alterações sem interrupções. Por exemplo, se o YouTube adicionar novas tags XML a respostas da API, o seu código deverá ignorar essas tags.

  • As diretrizes também definem funcionalidades da API que o YouTube não pretende alterar ao atualizar uma versão específica da API. Em outras palavras, essas funcionalidades serão alteradas apenas se o YouTube lançar uma nova versão da API, e o seu código não precisa tentar manipular esses tipos de alterações.

Sobre este documento

Este documento contém as seguintes seções:

  • A seção Solicitações da API define as diretrizes de compatibilidade com versões anteriores relacionadas a cabeçalhos de solicitações HTTP, parâmetros de solicitações da API, nomes de elementos XML (do modo como aparecem nas solicitações da API) e solicitações da API com formato incorreto.

  • A seção Respostas da API define as diretrizes de compatibilidade com versões anteriores relacionadas a nomes de elementos XML (do modo como aparecem nas respostas da API) e à posição das tags e atributos XML nas respostas da API.

  • A seção Melhores práticas descreve as recomendações para integrar a API do YouTube ao seu aplicativo cliente.

Solicitações da API

Funcionalidades sem perspectiva de alteração

  • Parâmetros de solicitação existentes.

  • Valores de parâmetros existentes para os parâmetros que possuem valores enumerados ou os significados desses valores de parâmetro.

  • Os nomes dos elementos XML usados nas solicitações POST (inserir) ou PUT (atualizar) da API.

  • O conjunto de cabeçalhos obrigatórios de solicitações HTTP para cada tipo de solicitação da API. Esta diretriz significa que o YouTube não pretende adicionar cabeçalhos obrigatórios de solicitações HTTP ou alterar cabeçalhos opcionais de solicitações para que se tornem obrigatórios.

  • O comportamento de ignorar parâmetros não suportados em uma solicitação da API, a menos que a solicitação use o parâmetro strict, o qual instrui o YouTube a rejeitar uma solicitação da API que contém parâmetros de solicitação inválidos.

Funcionalidades que poderão ser alteradas

  • O YouTube pode adicionar parâmetros opcionais de solicitação.

  • O YouTube pode adicionar novos valores para parâmetros existentes que tenham conjuntos de valores enumerados.

  • O YouTube pode rejeitar qualquer solicitação na qual os parâmetros válidos contenham valores de parâmetro inválidos. Como resultado, as solicitações com formato incorreto que foram aceitas devido a uma análise muito tolerante poderão ser rejeitadas se a lógica da análise for corrigida.

  • O YouTube pode adicionar cabeçalhos opcionais de solicitações HTTP.

  • O YouTube pode alterar as informações que ele retém (armazena) ao inserir ou atualizar um recurso. No entanto, essa decisão não afetará ou exigirá alterações na sintaxe das solicitações da respectiva API.

  • O YouTube pode alterar o conjunto de categorias pesquisáveis ou o conjunto de categorias às quais os vídeos recém-enviados podem ser atribuídos.

  • As funcionalidades não documentadas podem ser removidas ou alteradas a qualquer momento.

Respostas da API

Funcionalidades sem perspectiva de alteração

  • Nomes de tags XML existentes.

  • Seguir a especificação do módulo Media RSS para determinar a ordem dos elementos definidos nessa especificação e que aparecem várias vezes em uma entrada de feed. Por exemplo, se uma entrada contiver várias tags <media:thumbnail>, elas serão ordenadas de acordo com sua relevância.

  • O valor do atributo term da tag <category> que identifica o tipo de item descrito em um feed ou em uma entrada de feed. Na tag <feed> ou <entry>, a tag <id> especifica o recurso exclusivo identificado pela entrada e uma tag <category> identifica o tipo de recurso descrito pela entrada. Para a tag <category>, o valor do atributo scheme é http://schemas.google.com/g/2005#kind e o valor do atributo term indica se as entradas de feed descrevem vídeos, links de listas de reprodução, inscrições, contatos ou outro tipo de entidade.

Funcionalidades que poderão ser alteradas

  • O YouTube pode adicionar novas tags XML às respostas da API.

  • O YouTube pode adicionar novos atributos às tags XML existentes.

  • As tags existentes da API podem ser repetidas com valores diferentes. Por exemplo, o YouTube poderá adicionar uma nova tag <media:restriction> com um valor type diferente ou uma nova tag <media:credit> com scheme e role diferentes.

  • A ordem das tags e dos atributos XML na resposta da API pode ser alterada.

  • Tags filhas opcionais podem ser removidas das respostas da API.

  • As funcionalidades não documentadas podem ser removidas ou alteradas a qualquer momento.

Melhores práticas

  • Use o valor da tag <id> para identificar uma entrada.

  • Use o link self para recuperar uma entrada.

  • Use o link edit para editar ou atualizar uma entrada.

  • Use o valor da tag <yt:videoid> de uma entrada de vídeo para obter o valor que o YouTube usa para identificar exclusivamente esse vídeo. Não tente obter o ID do vídeo a partir de um link.

  • Use os URLs identificados nas tags <link>, <content> e <gd:feedLink> para navegar entre os feeds. O YouTube suporta um conjunto limitado de URLs que você pode construir com segurança para recuperar feeds específicos. Com exceção dos URLs de feed que estão listados a seguir, você não deve construir seus próprios URLs de feed, pois eles poderão parar de funcionar inesperadamente.

    • /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 (consulte o Guia de referência para obter mais informações)
  • Use o valor da tag <yt:videoid> de uma entrada de vídeo para obter o valor que o YouTube usa para identificar exclusivamente esse vídeo. Não tente obter o ID do vídeo a partir de um link.

  • Não tente obter os identificadores numéricos ou alfanuméricos a partir dos URLs de uma resposta da API. As respostas da API incluem tags específicas para os identificadores que possuem links para recursos no site do YouTube, como IDs de vídeos (<yt:videoid>) e nomes de usuário (<name> e <media:credit>).).

  • Se você enviar uma solicitação à API para inserir (POST) ou atualizar (PUT) informações, use a resposta XML fornecida para essa solicitação para determinar quais valores de tag na solicitação foram realmente armazenados pelo YouTube. Conforme consta nas diretrizes de compatibilidade com versões anteriores para solicitações da API, o YouTube pode alterar as informações retidas (armazenadas) quando inserir ou atualizar um recurso, o que significa que algumas tags na solicitação podem ser ignoradas.

  • Quando você recuperar um feed XML, armazene as tags e os atributos XML não reconhecidos relacionados a uma entrada de feed, se o seu aplicativo permitir que o usuário atualize essa entrada. Se o usuário atualizar o recurso, o seu aplicativo deverá incluir todas as tags e atributos não reconhecidos na solicitação de atualização. Isso garantirá que o seu aplicativo não exclua acidentalmente informações relacionadas aos novos recursos da API no processo de atualização de um recurso.

    O exemplo a seguir demonstra esta prática recomendada:

    1. O seu aplicativo permite que um usuário atualize uma descrição de vídeo.
    2. O seu aplicativo recupera a entrada de vídeo usando a API, mas não reconhece uma tag da entrada.
    3. O usuário modifica a descrição do vídeo.
    4. O seu aplicativo precisa enviar uma entrada completa de vídeo de volta para a API. A entrada precisa incluir a tag não reconhecida da etapa 2; caso contrário, esse valor poderá ser excluído.

  • Confirme se existe uma tag com um valor não nulo antes de tentar exibir o valor da tag.

  • Conforme mencionado anteriormente, o YouTube pode adicionar novos valores para tags ou atributos existentes que possuem conjuntos de valores enumerados. Via de regra, o seu código deve analisar os valores dos elementos XML que contêm conjuntos de valores enumerados e, em seguida, definir as ações apropriadas para esses valores. Esta prática é recomendável mesmo que apenas um valor possível do elemento seja enumerado.

    Por exemplo, a tag <media:credit> identifica o proprietário de um vídeo. O único valor documentado para o atributo role da tag é uploader, o qual indica que o vídeo foi enviado por um parceiro do YouTube. Esta prática recomendável determina que o seu aplicativo deve confirmar se o valor do atributo role da tag é realmente uploader antes de identificar o respectivo usuário como o proprietário do vídeo. (Esta precaução garantirá que o seu código não identifique o proprietário errado do vídeo se o YouTube adicionar outros tipos de créditos – por exemplo, diretor – para um vídeo.)

    • Se uma tag tiver um conjunto de valores enumerados e você não reconhecer o valor dessa tag, ignore toda a <entry> na qual essa tag é exibida.

    • Ignore uma entrada de feed de inscrição se você não reconhecer o valor do atributo term para a tag <category> que tiver um valor do atributo scheme igual a http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Essa tag específica identifica o tipo de inscrição identificado pela entrada. Se o seu aplicativo não reconhecer o tipo de inscrição, ele não deverá exibir informações sobre essa entrada.

    • Se algum outro atributo tiver um conjunto de valores enumerados e você não reconhecer o valor desse atributo, ignore a tag na qual o atributo é exibido.

  • O código do seu aplicativo deve esperar a mensagem yt:error a qualquer momento. No caso de uma operação da API falhar, o seu aplicativo deverá identificar o erro e exibir uma mensagem relevante para o usuário.

  • O YouTube pode adicionar novas categorias para a classificação dos vídeos a qualquer momento. O YouTube também pode atualizar ou remover categorias existentes. Você pode recuperar um arquivo atual de categorias em http://gdata.youtube.com/schemas/2007/categories.cat.

    • Se o seu aplicativo permitir que os usuários procurem vídeos por categoria ou enviem vídeos, recupere um arquivo de categorias atualizado semanalmente.

    • Se o seu aplicativo permitir que os usuários procurem vídeos por categoria, recupere também um arquivo atualizado de categorias se a API retornar um feed vazio em resposta a uma pesquisa de categoria.

    • Se o seu aplicativo permitir que os usuários enviem vídeos, recupere também um arquivo atualizado de categorias antes de enviar um vídeo e confirme se a categoria associada ao vídeo enviado ainda pode ser usada. Consulte o Guia de referência para obter mais informações. (Observe que se você tentar atribuir um vídeo a uma categoria que não está mais em uso, a API retornará uma mensagem de erro para a qual o valor da tag <code> será deprecated.)

  • Use as tags <link> de uma resposta da API para identificar os links de paginação para a página anterior e/ou para a próxima página de entradas em um feed. Consulte a seção Como paginar pelos resultados do Guia de referência para obter mais informações.