Présentation du guide du développeur

Avertissement: Cette page concerne les anciennes API Google, les API Google Data. Elle ne concerne que les API répertoriées dans l'annuaire des API Google Data, dont la plupart ont été remplacées par de nouvelles API. Pour en savoir plus sur une nouvelle API spécifique, consultez sa documentation. Pour en savoir plus sur l'autorisation des requêtes avec une API plus récente, consultez Authentification et autorisation des comptes Google.

Google a pour mission d'organiser à l'échelle mondiale les informations dans le but de les rendre accessibles et utiles à tous. Par exemple, ils ne doivent pas rendre les informations accessibles dans un contexte autre qu'un navigateur Web et les rendre accessibles à des services extérieurs à Google.

Le protocole de données Google offre aux développeurs externes un moyen sécurisé de développer de nouvelles applications qui permettent aux utilisateurs finaux d'accéder aux données stockées par de nombreux produits Google et de les mettre à jour. Les développeurs externes peuvent utiliser le protocole de données Google directement ou utiliser n'importe quel langage de programmation compatible fourni par les bibliothèques clientes.

Audience

Cet ensemble de documents est destiné à toute personne souhaitant comprendre le protocole Google Data. Même si vous souhaitez simplement écrire du code utilisant des bibliothèques clientes spécifiques à chaque langage, cet ensemble de documents peut vous être utile si vous voulez comprendre ce qui se passe sous la couche d'abstraction de la bibliothèque cliente.

Si vous recherchez le guide du développeur pour une API spécifique, consultez l'annuaire des API de Google Data Protocol.

Si vous souhaitez accéder à une API dans votre langage de programmation favori, consultez la page de téléchargement Bibliothèques clientes.

Contexte

Un certain nombre de produits Google, tels que Google Agenda et Google Sheets, fournissent des API basées sur le protocole de données Google. En tant que développeur, vous pouvez utiliser ces API pour développer des applications clientes offrant aux utilisateurs finaux de nouvelles façons d'accéder aux données qu'ils stockent dans ces produits et de les manipuler.

Remarque:Les produits Google qui fournissent des API sont parfois appelés services dans ces documents et dans d'autres documents associés.

Si vous écrivez du code qui utilise directement le protocole de données Google, celui-ci accède à l'API à l'aide de requêtes HTTP telles que GET ou POST. Grâce à ces demandes, les données stockées par le produit Google sont transférées de façon répétée sous forme de flux de données. Les flux de données sont de simples listes structurées contenant les données. Auparavant, le format de flux principal était au format XML AtomPub, mais désormais JSON ou JavaScript Object Notation, est également disponible en tant que autre format.

Si vous préférez ne pas écrire de code qui envoie directement des requêtes HTTP, vous pouvez programmer votre application cliente à l'aide de l'un des langages de programmation disponibles dans l'ensemble des bibliothèques clientes fournies. Les détails des requêtes HTTP sont alors gérés par la bibliothèque cliente. Vous écrivez votre code à un niveau plus conceptuel à l'aide des méthodes et des classes spécifiques à chaque langage fournies par la bibliothèque cliente.

Reportez-vous à la documentation spécifique au produit pour en savoir plus sur les langages spécifiques disponibles pour l'API, ou la version de l'API que vous utilisez.

Versions du protocole

Protocole 2.0 et version 1.0

La première version du protocole de données Google a été développée avant la finalisation du protocole de publication Atom. La deuxième version du protocole de données Google est entièrement conforme à la norme AtomPub RFC 5023.

La version 2.0 du protocole de données Google est également compatible avec:

  • ETags HTTP : Norme Web qui aide vos applications clientes à mieux utiliser la mise en cache HTTP. Les services inclus dans les bibliothèques clientes qui prennent en charge le protocole v2.0 gèrent automatiquement les ETags.
  • Réponse partielle et Mise à jour partielle (fonctionnalité expérimentale). Fonctionnalités permettant d'envoyer moins de données En demandant uniquement les informations dont vous avez réellement besoin ou en envoyant des mises à jour qui ne comprennent que les données que vous souhaitez vraiment modifier, votre application cliente peut être beaucoup plus efficace dans son utilisation des ressources réseau, processeur et mémoire. Actuellement, la réponse partielle et la mise à jour partielle ne sont disponibles que pour certains produits. Consultez la documentation spécifique au produit pour savoir si votre API le permet.

Mise à jour de votre application

Si l'API que vous utilisez a été créée avec la dernière version du protocole, la fonctionnalité du protocole v2.0 est incluse dans sa documentation. En général, nous vous recommandons de mettre à niveau votre application cliente vers la dernière version disponible pour votre API.

Mettre à jour un client basé sur une bibliothèque cliente

Si votre application cliente utilise une bibliothèque cliente, telle que la bibliothèque cliente Java ou la bibliothèque cliente .NET, elle peut contenir une version de l'API compatible avec les fonctionnalités du protocole v2.0. Pour le savoir, consultez la documentation de l'API du produit Google que vous utilisez pour savoir si les deux conditions suivantes sont remplies:

  • Il existe une version de l'API compatible avec les fonctionnalités de Google Data Protocol v2.0.
  • La bibliothèque cliente que vous utilisez est également compatible avec cette version de l'API.

Si la bibliothèque cliente le permet et que vous souhaitez mettre à jour votre application existante, il vous suffit de télécharger et d'utiliser la dernière version de la bibliothèque cliente. Tout votre code fonctionne toujours et la bibliothèque cliente s'occupe des modifications apportées au protocole v2.0 en arrière-plan.

Mettre à jour un client HTTP brut

Si vous avez écrit votre application cliente directement à l'aide du protocole de données Google, vous devez apporter les modifications suivantes:

  • Requêtes de version autres que celles par défaut. Ajoutez un en-tête de version HTTP (GData-Version: X.0) à chaque requête HTTP que vous envoyez, où X correspond à la version de l'API compatible avec les fonctionnalités du protocole Google Data v2.0. Vous pouvez également ajouter un paramètre de requête (v=X.0) à l'URL de chaque requête, où X est, là encore, la bonne version de l'API. Si vous ne spécifiez pas de version ultérieure, vos requêtes sont envoyées par défaut à la première version compatible de l'API.
  • Simultanéité optimale. Si vous utilisiez une version d'une API compatible avec la simultanéité optimiste, vous devrez peut-être modifier votre mise à jour et supprimer le code pour utiliser des ETag. Pour en savoir plus, consultez la section ETags de la documentation de référence du protocole de données Google, ainsi que les sections "Mettre à jour" et "Supprimer" du guide du développeur de protocoles pour le service utilisé par votre application cliente.
  • Auto-modifier ou modifier les URI. Si votre client effectue le suivi de ses propres URI ou modifie des URI pour des flux ou des entrées, notez que ces URI ont peut-être changé. Pour obtenir le nouvel URI, demandez à nouveau l'élément à l'aide de l'ancien URI, mais marquez la requête comme une requête de la version X.0, où X est la version de l'API compatible avec les fonctionnalités de Google Data Protocol v2.0. Le serveur renvoie la nouvelle représentation de l'entrée, y compris les nouveaux URI, que vous pouvez stocker à la place des anciens.
  • URI d'espaces de noms. Si votre client stocke les URI d'espace de noms de l'API Google Data Protocol localement ou les a codés en dur, vous devez les mettre à jour :
    • L'espace de noms AtomPub (préfixe app) est passé de http://purl.org/atom/app à http://www.w3.org/2007/app.
    • L'espace de noms OpenSearch (préfixe openSearch) est passé de http://a9.com/-/spec/opensearchrss/1.0/ à http://a9.com/-/spec/opensearch/1.1/.