Lineamientos de retrocompatibilidad

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

  • Es posible que YouTube publique actualizaciones de una versión específica de la API a la que no se le asigne un número de versión nuevo. Estas actualizaciones retrocompatibles 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 incompatibles con versiones anteriores de la API.

En este documento, se definen los lineamientos de retrocompatibilidad para las actualizaciones de una versión específica de la API, el primer elemento mencionado anteriormente. Los lineamientos buscan distinguir entre los siguientes tipos de funciones de 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 usar para controlar tus solicitudes a la API. Tu código debería controlar estos cambios sin errores. Por ejemplo, si YouTube agrega nuevas etiquetas XML a las respuestas de la API, tu código debe ignorarlas.

  • Los lineamientos también definen las funciones de la API que YouTube no tiene la intención de cambiar cuando actualiza una versión específica de la API. En otras palabras, solo debes esperar que esa funcionalidad cambie si YouTube lanza una nueva versión de la API, y tu código no debe intentar controlar este tipo de cambios.

Acerca de este documento

Este documento incluye las siguientes secciones:

  • En la sección Solicitudes a la API, se definen los lineamientos de retrocompatibilidad relacionados con los encabezados de solicitud HTTP, los parámetros de solicitud a la API, los nombres de elementos XML (tal como aparecen en las solicitudes a la API) y las solicitudes a la API con el formato incorrecto.

  • En la sección Respuestas de la API, se definen los lineamientos de retrocompatibilidad relacionados con los nombres de los elementos XML (tal 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.

  • En la sección Prácticas recomendadas, se describen las recomendaciones para integrar la API de YouTube en tu aplicación cliente.

Solicitudes a la API

Funcionalidad que no está destinada a cambiar

  • Parámetros de solicitud existentes.

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

  • Son los nombres de los elementos XML que se usan en las solicitudes POST (inserción) o PUT (actualización) de la API.

  • Es el conjunto de encabezados de solicitud HTTP que se requieren para cada tipo de solicitud a la API. Este lineamiento significa que YouTube no tiene la intención de agregar encabezados de solicitud HTTP obligatorios ni de cambiar los encabezados de solicitud opcionales existentes para que sean obligatorios.

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

Funcionalidad que puede cambiar

  • Es posible que YouTube agregue parámetros de solicitud opcionales.

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

  • YouTube puede rechazar cualquier solicitud en la que los parámetros válidos contengan valores no válidos. Como resultado, es posible que se rechacen las solicitudes con el formato incorrecto que se aceptaron debido a un análisis demasiado flexible si se corrige la lógica de análisis.

  • Es posible que YouTube agregue encabezados de solicitud HTTP opcionales.

  • Es posible que YouTube cambie la información que retiene (almacena) cuando inserta o actualiza un recurso. Sin embargo, esa decisión no afectaría ni requeriría cambios en la sintaxis de las solicitudes a la API correspondientes.

  • Es posible que YouTube cambie el conjunto de categorías que se pueden explorar o el conjunto de categorías a las que se pueden asignar los videos subidos recientemente.

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

Respuestas de la API

Funcionalidad que no está destinada a cambiar

  • Nombres de etiquetas XML existentes.

  • Seguir la especificación de RSS de contenido multimedia para determinar el orden de los elementos que se definen en esa especificación y que aparecen varias veces en una entrada de 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 elemento descrito en un feed o una entrada de 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. En 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 del feed describen videos, vínculos a playlists, suscripciones, contactos o algún otro tipo de entidad.

Funcionalidad que puede cambiar

  • Es posible que YouTube agregue nuevas etiquetas XML a las respuestas de la API.

  • Es posible que YouTube agregue atributos nuevos a las etiquetas XML existentes.

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

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

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

  • Las funciones 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 la etiqueta <yt:videoid> de una entrada de video para obtener el valor que YouTube usa para identificar de forma única ese video. No analices el ID de video a partir de un vínculo.

  • Usa las URLs identificadas en las etiquetas <link>, <content> y <gd:feedLink> para navegar entre los feeds. YouTube admite un conjunto limitado de URLs que puedes crear de forma confiable para recuperar feeds específicos. Además de las URLs de feed que se indican a continuación, no debes crear tus propias URLs de feed, ya que es posible que dejen 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 (consulta la guía de referencia para obtener más información)

  • No intentes analizar identificaciones numéricas o alfanuméricas de las URLs en una respuesta de la API. Las respuestas de la API incluyen etiquetas específicas para identificadores que vinculan a recursos en el sitio web de YouTube, como los IDs 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 de la solicitud almacenó YouTube. Como se indica en los lineamientos de retrocompatibilidad para las solicitudes a la API, YouTube puede cambiar la información que retiene (almacena) cuando se inserta o actualiza un recurso, lo que significa que es posible que se ignoren algunas de las etiquetas de la solicitud.

  • Cuando recuperes un feed XML, almacena las etiquetas y los atributos XML no reconocidos relacionados con una entrada de feed si tu aplicación permite que el usuario actualice 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 borre por error información relacionada con las nuevas funciones de la API durante 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 con 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, es posible que se borre ese valor.

  • Confirma que exista una etiqueta y que contenga un valor no nulo antes de intentar mostrar el valor de la etiqueta.

  • Como se indicó anteriormente, es posible que YouTube agregue valores nuevos para etiquetas o atributos existentes que tengan conjuntos enumerados de valores. Por lo general, tu código debe analizar los valores de los elementos XML que tienen conjuntos enumerados de valores y, luego, definir 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 para el atributo role de la etiqueta es uploader, que indica que un socio de YouTube subió el video. Esta práctica recomendada estipula que tu aplicación debe confirmar que el valor del atributo role de la etiqueta sea uploader antes de identificar al usuario correspondiente como el propietario del video. (Esta precaución garantiza que tu código no identifique de forma incorrecta al propietario de un video si YouTube agrega otros tipos de créditos, p.ej., el director).

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

    • Ignora una entrada del feed de suscripciones si no reconoces el valor del atributo term para la etiqueta <category> que tiene un valor del atributo scheme de 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 debe mostrar información sobre esa entrada.

    • Si algún otro atributo tiene un conjunto enumerado de valores y no reconoces el valor de ese atributo, debes ignorar la etiqueta en la que aparece.

  • El código de tu aplicación debe esperar un mensaje yt:error en cualquier momento. En caso de que falle una operación de la 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. Es posible que YouTube también actualice o dé 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 que los usuarios exploren videos por categoría o suban videos, recupera un archivo de categorías actualizado semanalmente.

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

    • Si tu aplicación permite que los usuarios suban videos, también recupera un archivo de categorías actualizado antes de subir un video y confirma que la categoría asociada con el video subido aún se pueda asignar. 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 en 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 anterior o siguiente de las entradas de un feed. Consulta la sección Paginación de resultados de la guía de referencia para obtener más información.