Directrices para la compatibilidad con versiones anteriores

En cada una de las solicitudes del API de datos de YouTube se puede especificar la versión del API que YouTube deberá utilizar para procesar dicha solicitud. Si no se especifica una versión del API en una solicitud, YouTube utilizará la versión admitida más antigua para procesar dicha solicitud. Actualmente, la versión admitida más antigua es 1. Ten en cuenta las siguientes características de los números de versión del API:

YouTube puede publicar actualizaciones de una versión específica del API sin asignarle un número de versión nuevo. Estas actualizaciones compatibles con las anteriores pueden incorporar funciones opcionales del API, corrección de errores o ambas opciones.
Si se publica una versión del API con un número de versión superior, significa que la versión contiene cambios que son incompatibles con las versiones anteriores del API.

En este documento se definen las directrices para la compatibilidad con actualizaciones anteriores de una versión específica del API (el primer elemento descrito anteriormente). En estas directrices se pretende establecer la diferencia entre los siguientes tipos de funciones del API:

Estas directrices identifican funciones del API que pueden cambiar, incluso si no modificas la versión del API que se debe utilizar para procesar las solicitudes del API. Tu código debe procesar estos cambios sin estropearse. Por ejemplo, si YouTube incorpora nuevas etiquetas XML a las respuestas del API, tu código deberá ignorarlas.
En estas directrices también se definen funciones del API que YouTube no piensa cambiar al actualizar una versión del API específica. En otras palabras, solamente puedes esperar que esa función cambie si YouTube publica una nueva versión del API y tu código no necesita procesar cambios de este tipo.

Acerca de este documento

Este documento consta de las siguientes secciones:

En la sección Solicitudes del API se definen las directrices para la compatibilidad con versiones anteriores en relación con los encabezados de solicitudes HTTP, con los parámetros de solicitudes del API, con los nombres de los elementos XML (tal y como aparecen en las solicitudes del API) y con las solicitudes incorrectas del API.
En la sección Respuestas del API se definen las directrices para la compatibilidad con versiones anteriores en relación con los nombres de los elementos XML (tal y como aparecen en las respuestas del API) y con el orden en el que aparecen los atributos y las etiquetas XML en las respuestas del API.
En la sección Prácticas recomendadas se ofrecen recomendaciones para integrar el API de YouTube en la aplicación cliente.

Solicitudes del API

Funciones que no van a cambiar

los parámetros de solicitudes existentes
los valores de parámetros existentes que tienen valores enumerados, ni el significado de dichos valores
los nombres de los elementos XML utilizados en las solicitudes POST (insertar) o en las solicitudes PUT (actualizar) del API
el conjunto de encabezamientos de solicitudes HTTP que se necesitan para cada tipo de solicitud del API (esta directriz hace referencia a que YouTube no piensa incorporar encabezamientos de solicitudes HTTP obligatorios ni hacer que los encabezamientos de solicitudes opcionales ya existentes sean obligatorios)
el hecho de ignorar los parámetros incompatibles incluidos en una solicitud del API (a menos que la solicitud utilice el parámetro strict, que indica que YouTube rechace una solicitud del API que contenga parámetros de solicitud no válidos)

Funciones que pueden cambiar

YouTube puede añadir parámetros de solicitud opcionales.
YouTube puede añadir valores nuevos a los parámetros existentes que tengan un conjunto de valores enumerados.
YouTube puede rechazar cualquier solicitud en la que los parámetros válidos contengan valores no válidos. En consecuencia, las solicitudes incorrectas que se hayan aceptado debido a un análisis demasiado benévolo se rechazarán si se corrige la lógica del análisis.
YouTube puede añadir encabezamientos de solicitudes HTTP opcionales.
YouTube puede cambiar la información que almacena cuando se inserta o se actualiza un recurso. Sin embargo, una decisión de ese tipo no afectaría a la sintaxis de las solicitudes del API correspondientes, ni requeriría que se introdujeran cambios en ella.
YouTube puede cambiar el conjunto de categorías de navegación o el conjunto de categorías a las que se pueden asignar los vídeos nuevos que se suben.
Las funciones que no aparecen documentadas se pueden eliminar o modificar en cualquier momento.

Respuestas del API

Funciones que no se van a modificar

nombres de etiquetas XML existentes
Seguimiento de la especificación Media RSS para determinar el orden de los elementos que se definen en dicha especificación y que aparecen varias veces en una entrada de feed. Por ejemplo, si una entrada contiene varias etiquetas <media:thumbnail>, estas se ordenan por importancia.
El valor del atributo term de la etiqueta <category> que identifica el tipo de elemento descrito en un feed o en una entrada de feed. En la etiqueta <feed> o <entry>, la etiqueta <id> especifica el recurso exclusivo identificado en la entrada, y la etiqueta <category> identifica el tipo de recurso descrito en la entrada. Para esta etiqueta <category>, el valor del atributo "scheme" es http://schemas.google.com/g/2005#kind y el valor del atributo "term" indica si las entradas de feeds describen vídeos, enlaces de listas de reproducción, suscripciones, contactos u otro tipo de entidad.

Funciones que pueden cambiar

YouTube puede incorporar nuevas etiquetas XML a las respuestas del API.
YouTube puede incorporar nuevos atributos a las etiquetas XML existentes.
Se pueden repetir las etiquetas del API existentes con diferentes valores. Por ejemplo, YouTube puede incorporar una nueva etiqueta <media:restriction> con un valor type diferente o una nueva etiqueta <media:credit> con los valores scheme y role diferentes.
Se puede modificar el orden de las etiquetas XML y de los atributos en la respuesta del API.
Se pueden eliminar las etiquetas secundarias opcionales de las respuestas del API.
Las funciones que no aparecen documentadas se pueden eliminar o modificar en cualquier momento.

Prácticas recomendadas

Utiliza el valor de la etiqueta <id> para identificar una entrada.
Utiliza el enlace self para recuperar una entrada.
Utiliza el enlace edit para editar o para actualizar una entrada.
Utiliza el valor de la etiqueta <yt:videoid> de una entrada de vídeo para obtener el valor que YouTube utiliza para identificar dicho vídeo de manera exclusiva. No analices la ID de vídeo de un enlace.
Utiliza las direcciones URL identificadas en las etiquetas <link>, <content> y <gd:feedLink> para navegar por los feeds. YouTube es compatible con un conjunto limitado de direcciones URL que puedes elaborar de forma fiable para recuperar feeds concretos. Aparte de estas URL de feeds que puedes ver a continuación, no debes elaborar tu propia URL de feed, ya que pueden dejar de funcionar de forma inesperada.
- /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 (más información en la Guía de referencia)
Utiliza el valor de la etiqueta <yt:videoid> de una entrada de vídeo para obtener el valor que YouTube utiliza para identificar dicho vídeo de manera exclusiva. No analices la ID de vídeo de un enlace.
No intentes analizar los identificadores numéricos ni alfanuméricos de las URL en una respuesta del API. Las respuestas del API incluyen etiquetas específicas para los identificadores que se vinculan a recursos del sitio web de YouTube como, por ejemplo, las ID de vídeo (<yt:videoid>) y los nombres de usuario (<name> y <media:credit>).
Si envías una solicitud del API para insertar (POST) o para actualizar (PUT) información, utiliza la respuesta XML a dicha solicitud para determinar qué valores de etiquetas de la solicitud ha almacenado YouTube realmente. Como se indica en el apartado solicitudes del API de las directrices para la compatibilidad con versiones anteriores, YouTube puede modificar la información que almacena cuando se inserta o se actualiza un recurso, por lo que pueden ignorarse algunas de las etiquetas de la solicitud.
Si tu aplicación permite que se actualicen entradas, cuando recuperes un feed XML, debes almacenar los atributos y las etiquetas XML que se desconozcan y que estén relacionados con una entrada de feed. Si el usuario actualiza el recurso, la aplicación debe incluir cualquier etiqueta y atributo desconocidos en la solicitud de actualización. Esto garantiza que la aplicación no borre de forma inesperada información relacionada con las nuevas funciones del API mientras se actualiza un recurso.

En el siguiente ejemplo se ilustra esta práctica recomendada:
1. Tu aplicación permite que un usuario actualice la descripción de un vídeo.
2. La aplicación recupera la entrada de vídeo mediante el API, pero no reconoce una de las etiquetas de la entrada.
3. El usuario modifica la descripción del vídeo.
4. La aplicación tiene que devolver al API una entrada de vídeo completa. La entrada debe incluir la etiqueta desconocida del paso 2; de lo contrario dicho valor puede eliminarse.
Confirma que la etiqueta existe y que contiene un valor que no sea nulo antes de intentar mostrar el valor de la etiqueta.
Como se mencionó anteriormente, YouTube puede incorporar nuevos valores a las etiquetas o a los atributos existentes que tienen conjuntos de valores enumerados. Como norma, tu código debe analizar los valores de los elementos XML que tienen conjuntos de valores enumerados y, a continuación, definir las acciones adecuadas para dichos valores. Esta práctica se recomienda incluso si solamente se enumera un valor posible para el elemento.

Por ejemplo, la etiqueta <media:credit> identifica el propietario de un vídeo. El único valor documentado para el atributo role de la etiqueta es uploader, que indica que el vídeo lo ha subido un partner de YouTube. Esta práctica recomendada estipula que tu aplicación debe confirmar que el valor del atributo role de la etiqueta es efectivamente uploader antes de identificar al usuario correspondiente como el propietario del vídeo. (Esta medida de precaución garantiza que tu código no identifique de forma incorrecta a un propietario de un vídeo si YouTube añade al vídeo otro tipo de créditos como, por ejemplo, director).
- Si una etiqueta tiene un conjunto de valores enumerados y no reconoces el valor de esa etiqueta, debes ignorar la entrada (<entry>) completa en la que aparezca la etiqueta.
- Ignora las entradas de feed de suscripciones si no reconoces el valor del atributo term de la etiqueta <category> cuyo valor del atributo scheme sea http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Esa etiqueta en concreto identifica el tipo de suscripción identificada por la entrada. Si la aplicación no reconoce el tipo de suscripción, no debe mostrar información sobre dicha entrada.
- Si cualquier otro atributo tiene un conjunto de valores enumerados y no reconoces el valor de ese atributo, debes ignorar la etiqueta en la que aparece.
El código de tu aplicación puede recibir un mensaje yt:error en cualquier momento. En caso de que se produzca un error en una operación del API, tu aplicación debe identificar el error y mostrar un mensaje significativo al usuario.
YouTube puede incorporar nuevas categorías para clasificar los vídeos en cualquier momento. YouTube también puede actualizar o desaprobar categorías ya existentes. Puedes obtener un archivo de categorías actualizado desde http://gdata.youtube.com/schemas/2007/categories.cat.
- Si tu aplicación permite a los usuarios buscar vídeos por categoría o subir vídeos, debes recuperar un archivo de categorías actualizado cada semana.
- Si tu aplicación permite a los usuarios buscar vídeos por categoría, también debes recuperar un archivo de categorías actualizado en caso de que el API devuelva un feed vacío como respuesta a una búsqueda por categoría.
- Si tu aplicación permite a los usuarios subir vídeos, también debes recuperar un archivo de categorías actualizado antes de subir un vídeo y así comprobar que la categoría a la que vas a asociar el vídeo existe todavía. Si deseas obtener más información, consulta la Guía de referencia. (Ten en cuenta que si intentas asignar un vídeo a una categoría no admitida, el API devolverá un mensaje de error cuyo valor de la etiqueta <code> será deprecated).
Utiliza las etiquetas <link> en las respuestas del API para identificar los enlaces de paginación a la página anterior o a la página siguiente de las entradas de un feed. Si deseas obtener más información, consulta la sección Paginación de los resultados de la Guía de referencia.