Consignes de rétrocompatibilité

Chaque requête de l'API YouTube Data peut spécifier la version de l'API que YouTube doit utiliser pour traiter cette requête. Si une requête ne spécifie pas de version d'API, YouTube utilisera la version la plus ancienne de l'API compatible pour traiter cette requête. La version la plus ancienne compatible 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 d'API spécifique à laquelle aucun nouveau numéro de version n'est attribué. Ces mises à jour rétrocompatibles peuvent inclure des fonctionnalités API facultatives, des corrections de bugs ou les deux.

• Une incrémentation du numéro de version de l'API identifie une version qui contient 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, premier élément de la liste ci-dessus. Les consignes visent à distinguer les types de fonctionnalités d'API suivants:

• Les consignes identifient les fonctionnalités de l'API susceptibles de changer, même si vous ne modifiez pas la version d'API à utiliser pour gérer vos requêtes d'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 les ignorer.

• Elles définissent également les fonctionnalités de l'API que YouTube n'a pas l'intention de modifier lors de la mise à jour d'une version spécifique de l'API. En d'autres termes, vous ne devez vous attendre à ce que cette fonctionnalité change que si YouTube publie une nouvelle version de l'API. Votre code n'a 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é concernant les en-têtes de requête HTTP, les paramètres de requête API, les noms d'éléments XML (tels qu'ils apparaissent dans les requêtes API) et les requêtes API mal formées.

• La section Réponses de l'API définit les consignes de rétrocompatibilité concernant les noms d'éléments XML (tels qu'ils apparaissent dans les réponses de l'API) et l'ordre dans lequel les balises et attributs XML apparaissent dans les réponses de l'API.

• La section Bonnes pratiques présente des recommandations pour intégrer l'API YouTube à votre application cliente.

Requêtes API

Fonctionnalités qui ne sont pas destinées à changer

• Paramètres de requête existants.

• Valeurs de paramètres existantes pour les paramètres dont les valeurs sont énumérées ou signification de ces valeurs de paramètre.

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

• 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 d'en-têtes de requête HTTP obligatoires ni de rendre obligatoires les en-têtes de requête facultatifs existants.

• Le comportement consistant à ignorer les paramètres non compatibles dans une requête API, sauf si la requête utilise le paramètre strict, qui indique à YouTube de rejeter une requête API contenant des paramètres de requête non valides.

Fonctionnalités susceptibles d'être modifiées

• YouTube peut ajouter des paramètres de requête facultatifs.

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

• YouTube peut refuser toute requête dans laquelle des paramètres valides contiennent des valeurs de paramètre non valides. Par conséquent, les requêtes mal formées qui ont été acceptées en raison d'une analyse trop indulgente peuvent être refusées si la logique d'analyse est corrigée.

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

• YouTube peut modifier les informations qu'il conserve (stocke) lors de l'insertion ou de la mise à jour d'une ressource. Toutefois, une telle décision n'aurait pas d'incidence sur la syntaxe des requêtes API correspondantes et ne nécessiterait pas de les modifier.

• YouTube peut modifier l'ensemble des catégories disponibles ou celles auxquelles les vidéos nouvellement mises en ligne peuvent être attribuées.

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

Réponses d'API

Fonctionnalités qui ne sont pas destinées à changer

• Noms de balises XML existants.

• Respecter la spécification RSS pour les médias afin de 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 de l'attribut term de la balise <category> qui identifie le type d'élément 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, et une balise <category> identifie le type de ressource décrit par l'entrée. Pour cette balise <category>, la valeur de l'attribut scheme est http://schemas.google.com/g/2005#kind, et la valeur de l'attribut term indique si les entrées de flux décrivent des vidéos, des liens vers des playlists, 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 balises API existantes peuvent être répétées avec différentes valeurs. Par exemple, YouTube peut ajouter une nouvelle 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 la balise <id> pour identifier une entrée.

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

• Utilisez le lien edit pour modifier une entrée.

• Utilisez la valeur de la balise <yt:videoid> pour une entrée vidéo afin d'obtenir la valeur que YouTube utilise pour identifier de manière unique 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 passer d'un flux à un autre. YouTube accepte un ensemble limité d'URL que vous pouvez créer de manière fiable pour récupérer des flux spécifiques. En dehors de ces URL de flux, listées ci-dessous, vous ne devez pas créer vos propres URL de flux, car elles risquent de ne plus 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 (pour en savoir plus, consultez le guide de référence)

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

• Si vous envoyez une requête API pour insérer (POST) ou mettre à jour (PUT) des informations, utilisez la réponse XML à cette requête pour déterminer quelles valeurs de balise de la requête ont été effectivement stockées par YouTube. Comme indiqué dans les consignes de rétrocompatibilité pour les requêtes API, YouTube peut modifier les informations qu'il conserve (stocke) lors de l'insertion ou de la mise à jour d'une ressource. Par conséquent, certaines des balises de la requête peuvent être ignorées.

• 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 mettre à jour cette entrée. Si l'utilisateur met à jour la ressource, votre application doit inclure les balises et attributs non reconnus dans la requête de mise à jour. Cette pratique garantit que votre application ne supprime pas par inadvertance les informations liées aux nouvelles fonctionnalités de l'API lors de la mise à jour d'une ressource.

  L'exemple suivant illustre cette bonne pratique:

  1. Votre application permet à un utilisateur de modifier 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 à l'API une entrée vidéo complète. L'entrée doit inclure la balise non reconnue de l'étape 2. Sinon, 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 sa valeur.

• Comme indiqué ci-dessus, YouTube peut ajouter de nouvelles valeurs pour les tags ou attributs existants qui comportent des ensembles de valeurs énumérés. En règle générale, votre code doit analyser les valeurs des éléments XML qui comportent des ensembles de valeurs énumérés, puis définir les actions approprié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 de la balise est uploader, qui indique que la vidéo a été mise en ligne par un partenaire YouTube. Cette bonne pratique stipule que votre application doit vérifier que la valeur de l'attribut role de la balise est bien uploader avant d'identifier l'utilisateur correspondant comme propriétaire de la vidéo. (Cette précaution permet de s'assurer 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 (par exemple, réalisateur) pour une vidéo.)

  • Si une balise comporte un ensemble de valeurs énumérées et que vous ne reconnaissez pas la valeur de cette balise, vous devez ignorer l'ensemble de l'<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 pour la balise <category> dont la valeur de l'attribut scheme est http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Cette balise identifie le type d'abonnement indiqué 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 de valeurs énumérées et que vous ne reconnaissez pas la valeur de cet attribut, vous devez ignorer la balise dans laquelle il apparaît.

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

• YouTube peut ajouter de nouvelles catégories pour classer les vidéos à tout moment. YouTube peut également mettre à jour ou abandonner des catégories existantes. Vous pouvez récupérer un fichier de catégories actuel sur http://gdata.youtube.com/schemas/2007/categories.cat.

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

  • Si votre application permet aux utilisateurs de parcourir les 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 de catégorie.

  • Si votre application permet aux utilisateurs d'importer des vidéos, récupérez également un fichier de catégories mis à jour avant d'importer une vidéo et vérifiez que la catégorie associée à la vidéo importée 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 renvoie un message d'erreur pour lequel la valeur de la balise <code> est deprecated.)

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