Consignes de rétrocompatibilité

Chaque demande d'API YouTube Data peut spécifier la version de l'API que YouTube doit utiliser pour traiter cette demande. Si une version de l'API n'est pas spécifiée, la version la plus ancienne de l'API est prise en charge par YouTube. La version compatible la plus ancienne est actuellement 1. Veuillez noter les caractéristiques suivantes des numéros de version de l'API:

• YouTube peut publier des mises à jour d'une version spécifique de l'API pour lesquelles aucun numéro de version n'a été attribué. Ces mises à jour rétrocompatibles peuvent inclure des fonctionnalités d'API facultatives, des corrections de bugs ou les deux.

• Un incrément du numéro de version de l'API identifie une version contenant des modifications incompatibles avec les versions précédentes de l'API.

Ce document définit les consignes de rétrocompatibilité pour les mises à jour d'une version d'API spécifique, le premier élément listé ci-dessus. Les consignes visent à distinguer les fonctionnalités d'API suivantes:

• Ces consignes identifient les fonctionnalités de l'API susceptibles de changer, même si vous ne modifiez pas la version de l'API à utiliser pour gérer vos requêtes API. Votre code doit gérer ces modifications sans interruption. Par exemple, si YouTube ajoute de nouvelles balises XML aux réponses de l'API, votre code doit ignorer ces balises.

• Ces consignes définissent également les fonctionnalités d'API que YouTube n'a pas l'intention de modifier lors de la mise à jour d'une version d'API spécifique. En d'autres termes, vous ne devez vous attendre à ce que cette fonctionnalité change si YouTube publie une nouvelle version de l'API. Votre code n'a donc pas besoin d'essayer de gérer ces types de modifications.

À propos de ce document

Ce document inclut les sections suivantes :

• La section Requêtes API définit les consignes de rétrocompatibilité liées aux en-têtes de requête HTTP, aux paramètres de requête d'API, aux noms d'éléments XML (tels qu'ils apparaissent dans les requêtes API) et aux requêtes API mal formées.

• La section Réponses de l'API définit les consignes de rétrocompatibilité liées aux noms d'élément XML (comme elles apparaissent dans les réponses de l'API), ainsi que l'ordre dans lequel les balises et les attributs XML apparaissent dans les réponses de l'API.

• La section Bonnes pratiques présente les recommandations concernant l'intégration de l'API YouTube à votre application cliente.

Requêtes API

Fonctionnalité non destinée à changer

• Paramètres de requête existants.

• Valeurs de paramètres existantes pour les paramètres ayant des valeurs énumérées ou leur signification.

• Noms des éléments XML utilisés dans les requêtes API POST (insertion) ou PUT (mise à jour).

• Ensemble d'en-têtes de requête HTTP requis pour chaque type de requête API. Cette consigne signifie que YouTube n'a pas l'intention d'ajouter les en-têtes de requête HTTP requis ni de modifier les en-têtes de requête facultatifs existants.

• Comportement qui ignore les paramètres non compatibles dans une requête API, sauf si cette dernière utilise le paramètre strict, qui indique à YouTube de rejeter une requête API contenant des paramètres non valides.

Fonctionnalités susceptibles d'être modifiées

• YouTube peut ajouter des paramètres de demande facultatifs.

• YouTube peut ajouter de nouvelles valeurs pour les paramètres existants comportant des ensembles de valeurs énumérés.

• Nous pouvons refuser toute demande contenant des paramètres non valides. Par conséquent, les requêtes mal formées qui ont été acceptées en raison d'une analyse trop permissive peuvent être refusées si la logique d'analyse est corrigée.

• YouTube peut ajouter des en-têtes de requêtes HTTP facultatifs.

• YouTube peut modifier les informations conservées (stockées) lors de l'insertion ou de la mise à jour d'une ressource. Toutefois, une telle décision n'aura aucune incidence sur la syntaxe des requêtes API correspondantes ni ne nécessitera de modification.

• YouTube peut modifier l'ensemble de catégories disponibles ou celles des nouvelles vidéos mises en ligne.

• Les fonctionnalités non documentées peuvent être supprimées ou modifiées à tout moment.

Réponses d'API

Fonctionnalité non destinée à changer

• Noms de balises XML existants.

• Suivre les spécifications Media RSS pour déterminer l'ordre des éléments définis dans cette spécification et qui apparaissent plusieurs fois dans une entrée de flux Par exemple, si une entrée contient plusieurs balises <media:thumbnail>, elles sont triées par ordre d'importance.

• Valeur d'attribut term de la balise <category> qui identifie le type d'article décrit dans un flux ou une entrée de flux. Dans la balise <feed> ou <entry>, la balise <id> spécifie la ressource unique identifiée par l'entrée, tandis que la balise <category> identifie le type de ressource décrit par l'entrée. Pour cette balise <category>, la valeur de l'attribut de schéma est http://schemas.google.com/g/2005#kind, et la valeur de l'attribut de terme indique si les entrées de flux décrivent des vidéos, des liens de playlist, des abonnements, des contacts ou un autre type d'entité.

Fonctionnalités susceptibles d'être modifiées

• YouTube peut ajouter de nouvelles balises XML aux réponses de l'API.

• YouTube peut ajouter de nouveaux attributs aux balises XML existantes.

• Les tags d'API existants peuvent être répétés avec différentes valeurs. Par exemple, YouTube peut ajouter une balise <media:restriction> avec une valeur type différente ou une nouvelle balise <media:credit> avec des valeurs scheme et role différentes.

• L'ordre des balises et des attributs XML dans la réponse de l'API peut changer.

• Les balises enfants facultatives peuvent être supprimées des réponses de l'API.

• Les fonctionnalités non documentées peuvent être supprimées ou modifiées à tout moment.

Bonnes pratiques

• Utilisez la valeur de tag <id> pour identifier une entrée.

• Utilisez le lien self pour récupérer une entrée.

• Utilisez le lien edit pour modifier ou mettre à jour une entrée.

• Utilisez la valeur de balise <yt:videoid> pour une entrée vidéo afin d'obtenir la valeur utilisée par YouTube pour identifier cette vidéo. N'analysez pas l'ID vidéo à partir d'un lien.

• Utilisez les URL identifiées dans les balises <link>, <content> et <gd:feedLink> pour naviguer entre les flux. YouTube n'accepte qu'un ensemble limité d'URL que vous pouvez créer de manière fiable pour récupérer des flux spécifiques. Hormis ces URL de flux, qui sont listées ci-dessous, vous ne devez pas créer vos propres URL de flux, car elles risquent de cesser de fonctionner de manière inattendue.

  • /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 (consultez le guide de référence pour en savoir plus)

• N'essayez pas d'analyser les identifiants numériques ou alphanumériques à partir d'URL dans une réponse de l'API. Les réponses de l'API incluent des tags spécifiques pour les identifiants qui redirigent vers des ressources sur le site Web YouTube, comme les ID vidéo (<yt:videoid>) et les noms d'utilisateur (<name> et <media:credit>).)

• Si vous envoyez une demande d'API pour insérer (POST) ou mettre à jour (PUT) des informations, utilisez la réponse XML à cette demande pour déterminer les valeurs de tag de la demande qui ont été réellement stockées par YouTube. Comme indiqué dans les consignes relatives à la rétrocompatibilité pour les requêtes API, YouTube peut modifier les informations qu'il conserve (magasins) lors de l'insertion ou de la mise à jour d'une ressource. Il est donc possible que certains tags soient ignorés.

• Lorsque vous récupérez un flux XML, stockez les balises et attributs XML non reconnus associés à une entrée de flux si votre application permet à l'utilisateur de la mettre à jour. Si l'utilisateur met à jour la ressource, votre application doit inclure tous les tags et attributs non reconnus dans la requête de mise à jour. Cette pratique garantit que votre application ne supprime pas par inadvertance des informations liées aux nouvelles fonctionnalités de l'API lors du processus de mise à jour d'une ressource.

  L'exemple suivant illustre cette bonne pratique:

  1. Votre application permet à un utilisateur de mettre à jour la description d'une vidéo.
  2. Votre application récupère l'entrée vidéo à l'aide de l'API, mais ne reconnaît pas l'un des tags de l'entrée.
  3. L'utilisateur modifie la description de la vidéo.
  4. Votre application doit renvoyer une entrée vidéo complète à l'API. L'entrée doit inclure la balise non reconnue de l'étape 2. Dans le cas contraire, cette valeur risque d'être supprimée.

• Vérifiez qu'une balise existe et qu'elle contient une valeur non nulle avant d'essayer d'afficher la valeur de la balise.

• Comme indiqué ci-dessus, YouTube peut ajouter de nouvelles valeurs pour des tags ou des attributs existants dont les ensembles de valeurs sont énumérés. En règle générale, votre code doit analyser les valeurs des éléments XML comportant des ensembles de valeurs énumérés, puis définir des actions adaptées à ces valeurs. Cette pratique est recommandée même si une seule valeur possible est énumérée pour l'élément.

  Par exemple, la balise <media:credit> identifie le propriétaire d'une vidéo. La seule valeur documentée pour l'attribut role du tag est uploader, ce qui indique que la vidéo a été mise en ligne par un partenaire YouTube. Cette bonne pratique stipule que votre application doit confirmer que la valeur de l'attribut role du tag est bien uploader avant d'identifier l'utilisateur correspondant comme étant le propriétaire de la vidéo. Cette précaution permet de garantir que votre code n'identifie pas de manière incorrecte le propriétaire d'une vidéo, si YouTube ajoute d'autres types de crédits (réalisateur, par exemple) pour une vidéo.

  • Si une balise contient un ensemble de valeurs énumérées et que vous ne reconnaissez pas la valeur de cette balise, vous devez ignorer l'intégralité de l'élément <entry> dans lequel elle apparaît.

  • Ignorez une entrée de flux d'abonnements si vous ne reconnaissez pas la valeur de l'attribut term de la balise <category> dont la valeur d'attribut scheme est http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Cette balise permet d'identifier le type d'abonnement identifié par l'entrée. Si votre application ne reconnaît pas le type d'abonnement, elle ne doit pas afficher d'informations sur cette entrée.

  • Si un autre attribut comporte un ensemble énuméré de valeurs et que vous ne reconnaissez pas la valeur de cet attribut, vous devez ignorer la balise dans laquelle l'attribut apparaît.

• Le code de votre application devrait recevoir un message yt:error à tout moment. En cas d'échec d'une opération de l'API, votre application doit identifier l'erreur et afficher un message pertinent à l'utilisateur.

• YouTube peut ajouter à tout moment de nouvelles catégories pour la classification des vidéos. YouTube peut également modifier ou rendre obsolètes certaines catégories. Vous pouvez récupérer un fichier de catégories actuel depuis http://gdata.youtube.com/schemas/2007/categories.cat.

  • Si votre application permet aux utilisateurs de parcourir des vidéos par catégorie ou de mettre en ligne des vidéos, vous pouvez récupérer un fichier de catégories mis à jour chaque semaine.

  • Si votre application permet aux utilisateurs de parcourir des vidéos par catégorie, récupérez également un fichier de catégories mis à jour si l'API renvoie un flux vide en réponse à une recherche par catégorie.

  • Si votre application permet aux utilisateurs de mettre en ligne des vidéos, vous pouvez également récupérer un fichier de catégories mis à jour avant de mettre en ligne une vidéo et confirmer que la catégorie associée à la vidéo mise en ligne peut toujours être attribuée. Pour en savoir plus, consultez le guide de référence. (Notez que si vous essayez d'attribuer une vidéo à une catégorie non attribuable, l'API affichera un message d'erreur pour lequel la valeur de la balise <code> est deprecated.)

• Utilisez les balises <link> dans une réponse de l'API afin d'identifier les liens de pagination pour la page d'entrées précédente et/ou suivante d'un flux. Pour en savoir plus, consultez la section Parcourir les résultats du guide de référence.