Pautas de compatibilidad con versiones anteriores

Cada solicitud de API de datos de YouTube puede especificar la versión de la API que YouTube debe usar para manejar esa solicitud. Si en una solicitud no se especifica una versión de la API, YouTube usará la versión compatible más antigua de la API para procesar esa solicitud. La versión compatible más antigua es 1. Ten en cuenta las siguientes características de los números de versión de API:

  • Es posible que YouTube lance una versión específica para la API a la que no se le haya asignado un número de versión nuevo. Estas actualizaciones compatibles con versiones anteriores pueden incluir funciones opcionales de la API, correcciones de errores o ambas.

  • Un incremento del número de versión de la API identifica una versión que contiene cambios que no son compatibles con las versiones de API anteriores.

En este documento, se definen los lineamientos de retrocompatibilidad para las actualizaciones de una versión específica de una API, el primer elemento que aparece arriba. Las pautas buscan distinguir entre los siguientes tipos de funcionalidades de la API:

  • Los lineamientos identifican la funcionalidad de la API que puede cambiar, incluso si no modificas la versión de la API que se debe utilizar para manejar tus solicitudes de API. Tu código debería manejar estos cambios sin romperse. Por ejemplo, si YouTube agrega nuevas etiquetas XML a las respuestas de la API, tu código debe ignorar esas etiquetas.

  • Los lineamientos también definen la funcionalidad de la API que YouTube no pretende cambiar al actualizar una versión específica de la API. En otras palabras, solo debes esperar que la funcionalidad cambie si YouTube lanza una nueva versión de API, y el código no necesita intentar manejar estos tipos de cambios.

Acerca de este documento

Este documento incluye las siguientes secciones:

  • La sección Solicitudes de API define las pautas de retrocompatibilidad relacionadas con los encabezados de solicitud HTTP, los parámetros de solicitud de API, los nombres de elementos XML (como aparecen en las solicitudes a la API) y las solicitudes de API no formuladas de manera correcta.

  • La sección Respuestas a la API define las pautas de retrocompatibilidad relacionadas con los nombres de elementos XML (como aparecen en las respuestas de la API) y el orden en que aparecen las etiquetas y los atributos XML en las respuestas de la API.

  • La sección Recomendaciones describe las recomendaciones para integrar la API de YouTube con tu aplicación cliente.

Solicitudes a la API

Funcionalidad que no cambia

  • Parámetros de solicitud existentes.

  • Valores de los parámetros existentes para los parámetros que tienen valores enumerados o el significado de esos valores.

  • Los nombres de los elementos XML que se usan en las solicitudes POST (update) o PUT (update) de las API.

  • El conjunto de encabezados de solicitud HTTP que se requieren para cada tipo de solicitud de API. Esta guía implica que YouTube no pretende agregar los encabezados de solicitud HTTP obligatorios ni cambiar los encabezados de solicitud opcionales existentes que se requerirán.

  • El comportamiento de ignorar parámetros no admitidos en una solicitud de API, a menos que la solicitud use el parámetro strict, que le indica a YouTube que rechace una solicitud de API que contiene parámetros de solicitud no válidos.

Funcionalidades que pueden cambiar

  • YouTube puede agregar parámetros opcionales de solicitud.

  • Es posible que YouTube agregue valores nuevos para los parámetros existentes que tengan conjuntos de valores enumerados.

  • YouTube puede rechazar cualquier solicitud en la que parámetros válidos contenga valores no válidos. Como resultado, las solicitudes con errores de formato que se hayan aceptado debido a un análisis demasiado tolerante pueden rechazarse si se corrige la lógica de análisis.

  • YouTube puede agregar encabezados de solicitud HTTP opcionales.

  • YouTube puede cambiar la información que retiene (almacena) cuando inserta o actualiza un recurso. Sin embargo, tal decisión no afectará ni requerirá cambios en la sintaxis de las solicitudes de API correspondientes.

  • YouTube puede cambiar el conjunto de categorías explorables o el conjunto de categorías a las que se pueden asignar los videos subidos recientemente.

  • Las funcionalidades no documentadas se pueden quitar o cambiar en cualquier momento.

Respuestas de la API

Funcionalidad que no cambia

  • Nombres de etiquetas XML existentes.

  • Se debe seguir la especificación de Media RSS para determinar el orden de los elementos que se definen en esa especificación y que aparecen varias veces en una entrada del feed. Por ejemplo, si una entrada contiene varias etiquetas <media:thumbnail>, se ordenan por importancia.

  • Es el valor del atributo term de la etiqueta <category> que identifica el tipo de artículo que se describe en un feed o una entrada del feed. Dentro de la etiqueta <feed> o <entry>, la etiqueta <id> especifica el recurso único que identifica la entrada, y una etiqueta <category> identifica el tipo de recurso que describe la entrada. Para esta etiqueta <category>, el valor del atributo de esquema es http://schemas.google.com/g/2005#kind y el valor del atributo indica si las entradas de feed describen videos, vínculos a listas de reproducción, suscripciones, contactos u otro tipo de entidad.

Funcionalidades que pueden cambiar

  • YouTube puede agregar etiquetas XML nuevas a las respuestas de la API.

  • YouTube puede agregar nuevos atributos a las etiquetas XML existentes.

  • Las etiquetas de API existentes pueden repetirse con valores diferentes. Por ejemplo, YouTube podría agregar una etiqueta <media:restriction> nueva con un valor type diferente o una etiqueta <media:credit> nueva con scheme y role diferentes.

  • El orden de las etiquetas XML y los atributos en la respuesta de la API puede cambiar.

  • Es posible que se quiten las etiquetas secundarias opcionales de las respuestas de la API.

  • Las funcionalidades no documentadas se pueden quitar o cambiar en cualquier momento.

Prácticas recomendadas

  • Usa el valor de la etiqueta <id> para identificar una entrada.

  • Usa el vínculo self para recuperar una entrada.

  • Usa el vínculo edit para editar o actualizar una entrada.

  • Usa el valor de etiqueta <yt:videoid> para una entrada de video a fin de obtener el valor que YouTube usa para identificar ese video de manera única. No analices el ID de video de un vínculo.

  • Use las URL identificadas en las etiquetas <link>, <content> y <gd:feedLink> para navegar entre los feeds. YouTube admite un conjunto limitado de URL que puedes construir para recuperar feeds específicos. Aparte de las URL de feed, que se enumeran a continuación, no debe crear sus propias URL de feed, ya que podrían dejar 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 la guía de referencia para obtener más información)

  • No intentes analizar identificaciones numéricas o alfanuméricas a partir de URL en una respuesta de la API. Las respuestas de la API incluyen etiquetas específicas para los identificadores que vinculan a recursos en el sitio web de YouTube, como las identificaciones de video (<yt:videoid>) y los nombres de usuario (<name> y <media:credit>).)

  • Si envías una solicitud a la API para insertar (POST) o actualizar (PUT) información, usa la respuesta XML a esa solicitud para determinar qué valores de etiqueta en la solicitud se almacenaron realmente en YouTube. Como se indica en los lineamientos de retrocompatibilidad con las solicitudes de API, YouTube puede cambiar la información que retiene (almacena) cuando inserta o actualiza un recurso, lo que significa que algunas de las etiquetas de la solicitud pueden ignorarse.

  • Cuando recuperas un feed XML, almacena etiquetas XML no reconocidas y atributos relacionados con una entrada de feed si tu aplicación le permite al usuario actualizar esa entrada. Si el usuario actualiza el recurso, tu aplicación debe incluir las etiquetas y los atributos no reconocidos en la solicitud de actualización. Esta práctica garantiza que tu aplicación no elimine inadvertidamente información relacionada con nuevas características de la API en el proceso de actualización de 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 video.
    2. Tu aplicación recupera la entrada de video mediante la API, pero no reconoce una de las etiquetas de la entrada.
    3. El usuario modifica la descripción del video.
    4. Tu aplicación debe enviar una entrada de video completa a la API. La entrada debe incluir la etiqueta no reconocida del paso 2; de lo contrario, podría eliminarse ese valor.

  • Verifique que exista una etiqueta y que contenga un valor no nulo antes de intentar mostrarla.

  • Como se mencionó anteriormente, YouTube puede agregar valores nuevos para las etiquetas o los atributos existentes que tienen conjuntos de valores enumerados. Como regla general, tu código debe analizar los valores de los elementos XML que tienen conjuntos de valores enumerados y, luego, definir las acciones adecuadas para esos valores. Se recomienda esta práctica incluso si solo se enumera un valor posible para el elemento.

    Por ejemplo, la etiqueta <media:credit> identifica al propietario de un video. El único valor documentado del atributo role de la etiqueta es uploader, el cual indica que un socio de YouTube subió el video. Esta práctica recomendada establece que tu aplicación debe confirmar que el valor del atributo role de la etiqueta sea uploader antes de identificar al usuario correspondiente como propietario del video. (Esta precaución garantiza que tu código no identifique incorrectamente a un propietario de video si YouTube agrega otros tipos de créditos, por ejemplo, un director) para un video.

    • Si una etiqueta tiene un conjunto de valores enumerados y no reconoces el valor de esa etiqueta, debes ignorar todo el <entry> dentro de la que aparece esa etiqueta.

    • Omite una entrada del feed de suscripciones si no reconoces el valor del atributo term de la etiqueta <category> que tiene un valor scheme para el atributo http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Esa etiqueta en particular identifica el tipo de suscripción que identifica la entrada. Si tu aplicación no reconoce el tipo de suscripción, no debería mostrar información sobre esa entrada.

    • Si cualquier otro atributo tiene un conjunto de valores enumerados y no reconoce el valor de ese atributo, debe ignorar la etiqueta en la que aparece el atributo.

  • El código de tu aplicación debería recibir un mensaje yt:error en cualquier momento. En caso de que falle una operación de API, tu aplicación debe identificar el error y mostrar un mensaje significativo al usuario.

  • YouTube puede agregar categorías nuevas para clasificar videos en cualquier momento. YouTube también puede actualizar o dar de baja las categorías existentes. Puedes recuperar un archivo de categorías actual en http://gdata.youtube.com/schemas/2007/categories.cat.

    • Si tu aplicación permite a los usuarios explorar videos por categoría o subir videos, recupera un archivo de categorías actualizado semanalmente.

    • Si tu aplicación permite a los usuarios explorar videos por categoría, también recupera un archivo de categorías actualizado si la API devuelve un feed vacío en respuesta a una búsqueda por categoría.

    • Si tu aplicación permite que los usuarios suban videos, recupera también un archivo de categorías actualizado antes de subir un video y confirma que la categoría asociada con el video subido pueda asignarse de todos modos. Consulta la guía de referencia para obtener más información. (Ten en cuenta que si intentas asignar un video a una categoría no asignable, la API mostrará un mensaje de error para el que el valor de la etiqueta <code> es deprecated).

  • Usa las etiquetas <link> en una respuesta de la API para identificar los vínculos de paginación de la página de entradas anterior o siguiente en un feed. Consulta la sección Cómo desplazarse por los resultados de la guía de referencia para obtener más información.