Cette page a été traduite par l'API Cloud Translation.

Premiers pas

Ce document présente en détail les connaissances de base dont vous avez besoin pour utiliser l'API Google Livres.

Introduction
Avant de commencer
Arrière-plan de l'API Livres
Style d'appel
1. REST
Format des données
1. JSON

Introduction

Ce document est destiné aux développeurs qui souhaitent développer des applications pouvant interagir avec l'API Google Livres. Google Livres a pour ambition de numériser les livres à l'échelle mondiale. Vous pouvez utiliser l'API Google Livres pour rechercher du contenu, organiser la bibliothèque personnelle d'un utilisateur authentifié et la modifier.

Avant de commencer

Obtenir un compte Google

Vous avez besoin d'un compte Google à des fins de test. Si vous disposez déjà d'un compte test, vous êtes prêt. Vous pouvez visiter l'interface utilisateur de Google Livres pour configurer, modifier ou afficher vos données de test.

Se familiariser avec Livres

Si vous ne connaissez pas les concepts de Google Livres, nous vous recommandons de lire ce document et de tester l'interface utilisateur avant de commencer à coder. Dans ce document, nous partons du principe que vous connaissez les concepts de programmation Web et les formats de données Web.

En savoir plus sur l'autorisation des requêtes et l'identification de votre application

Lorsque votre application demande des données privées, la requête doit être autorisée par un utilisateur authentifié qui a accès à ces données.

En particulier, toutes les opérations figurant sous "Ma bibliothèque" dans l'API Google Livres sont considérées comme privées et nécessitent une authentification et une autorisation. De plus, toute opération qui modifie les données Google Livres ne peut être effectuée que par l'utilisateur propriétaire de ces données.

Lorsque votre application demande des données publiques, la requête n'a pas besoin d'être autorisée, mais doit être accompagnée d'un identifiant, tel qu'une clé API.

Pour en savoir plus sur l'autorisation des requêtes et l'utilisation des clés API, consultez la section Autoriser les requêtes et identifier votre application dans le document "Utiliser l'API".

Contexte de l'API Books

Concepts de livres

Google Livres repose sur quatre concepts fondamentaux:

Volume: un volume représente les données hébergées par Google Livres à propos d'un livre ou d'un magazine. Il s'agit de la ressource principale de l'API Books. Toutes les autres ressources de cette API contiennent ou annotent un volume.
Bookshelf: une étagère est un ensemble de volumes. Google Livres fournit un ensemble d'étagères prédéfinies pour chaque utilisateur. Certaines sont entièrement gérées par l'utilisateur, d'autres sont automatiquement remplies en fonction de l'activité de l'utilisateur, et d'autres sont mixtes. Les utilisateurs peuvent créer, modifier ou supprimer d'autres étagères, qui sont toujours remplies manuellement. Les étagères peuvent être rendues privées ou publiques par l'utilisateur.
Remarque:Pour le moment, la création et la suppression d'étagères, ainsi que la modification de leurs paramètres de confidentialité, ne peuvent être effectuées que sur le site Google Livres.
Avis: un avis sur un volume est une combinaison d'étoiles et/ou de texte. Un utilisateur ne peut envoyer qu'un seul avis par volume. Les avis sont également disponibles depuis des sources externes et sont attribués de manière appropriée.
Position de lecture: pour un utilisateur, une position de lecture indique la dernière position de lecture d'un volume. Un utilisateur ne peut avoir qu'un seul marque-page par volume. Si l'utilisateur n'a pas ouvert ce volume auparavant, la position de lecture n'existe pas. La position de lecture peut stocker des informations de position détaillées jusqu'à la résolution d'un mot. Ces informations sont toujours réservées à l'utilisateur.

Modèle de données de l'API Livres

Une ressource est une entité de données individuelle disposant d'un identifiant unique. L'API Books fonctionne sur deux types de ressources, en fonction des concepts décrits ci-dessus:

Ressource de volume: représente un volume.
Ressource étagère: représente une étagère unique pour un utilisateur donné.

Le modèle de données de l'API Livres est basé sur des groupes de ressources, appelés collections:

Collecte des volumes: La collection de volumes est une collection regroupant toutes les ressources de volume gérées par Google Livres. Ainsi, vous ne pouvez pas répertorier toutes les ressources de volume, mais vous pouvez répertorier tous les volumes correspondant à un ensemble de termes de recherche.
Collection d'étagères: Une collection "étagère" comprend toutes les ressources "étagère" gérées par Google Livres. Les étagères doivent toujours être référencées dans le contexte de la bibliothèque d'un utilisateur spécifique. Les étagères peuvent contenir plusieurs volumes ou aucun.

Opérations de l'API Livres

Vous pouvez appeler cinq méthodes différentes sur les collections et les ressources dans l'API Livres, comme décrit dans le tableau suivant.

Opération	Description	Mappages HTTP REST
liste	Répertorie un sous-ensemble spécifié de ressources dans une collection.	`GET` sur un URI de collection.
insérer	Insère une nouvelle ressource dans une collection (création d'une ressource).	`POST` sur un URI de collection, où vous transmettez des données pour une nouvelle ressource.
get	Récupère une ressource spécifique.	`GET` sur l'URI de la ressource.
mise à jour	Met à jour une ressource spécifique.	`PUT` sur l'URI de la ressource, où vous transmettez des données pour la ressource mise à jour.
supprimer	Supprime une ressource spécifique.	`DELETE` sur l'URI de la ressource, où vous transmettez des données pour la ressource à supprimer.

Le tableau ci-dessous récapitule les opérations compatibles avec les différents types de ressources. Les opérations qui s'appliquent aux données privées d'un utilisateur sont appelées "Ma bibliothèque". Elles nécessitent toutes une authentification.

Type de ressource	Opérations compatibles
	liste	insérer	get	mise à jour	supprimer
Volumes	oui*		oui
Étagères	oui*	oui, AUTHENTICATED	oui*	oui, AUTHENTICATED	oui, AUTHENTICATED
Lecture des positions		oui, AUTHENTICATED	oui, AUTHENTICATED	oui, AUTHENTICATED	oui, AUTHENTICATED

*Des versions AUTHENTIFIÉES et non authentifiées de ces opérations sont disponibles. Les requêtes authentifiées opèrent sur les données privées "Ma bibliothèque" de l'utilisateur, tandis que les requêtes non authentifiées ne s'exécutent que sur les données publiques.

Styles d'appel

Il existe plusieurs façons d'appeler l'API:

Utiliser REST directement
Utiliser REST à partir de JavaScript (aucun code côté serveur requis)

REST

Il s'agit d'un style d'architecture logicielle qui permet de demander et modifier des données de manière pratique et cohérente.

Le terme REST est l'acronyme de Representational State Transfer. Dans le contexte des API Google, il désigne l'utilisation de verbes HTTP pour extraire et modifier des représentations de données stockées par Google.

Dans un système RESTful, les ressources sont stockées dans un datastore. Un client envoie une requête pour que le serveur exécute une action spécifique (par exemple la création, l'extraction, la mise à jour ou la suppression d'une ressource), et le serveur exécute l'action et envoie une réponse, souvent sous la forme d'une représentation de la ressource spécifiée.

Dans les API RESTful de Google, le client spécifie une action à l'aide d'un verbe HTTP tel que POST, GET, PUT ou DELETE. Il spécifie une ressource par un URI globalement unique au format suivant:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Étant donné que toutes les ressources d'API possèdent des URI uniques accessibles via HTTP, REST permet la mise en cache des données, et son fonctionnement est optimisé pour l'infrastructure distribuée du Web.

Les définitions de méthode figurant dans la documentation du standard HTTP 1.1 peuvent s'avérer utiles, car elles incluent les spécifications pour GET, POST, PUT, et DELETE.

REST dans l'API Livres

Les opérations Livres compatibles sont mappées directement à des verbes HTTP REST, comme décrit dans la section Opérations de l'API Livres.

Le format spécifique des URI de l'API Livres est le suivant:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

où resourceID est l'identifiant d'une ressource de volume ou de bibliothèque, et parameters représente tous les paramètres à appliquer à la requête. Pour en savoir plus, consultez la documentation de référence sur les paramètres de requête.

Le format des extensions de chemin resourceID vous permet d'identifier la ressource en cours d'utilisation, par exemple:

https://www.googleapis.com/books/v1/volumes
https://www.googleapis.com/books/v1/volumes/volumeId
https://www.googleapis.com/books/v1/mylibrary/bookshelves
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
...

Notez que les opérations dont l'URI contient mylibrary ne s'appliquent qu'aux données de bibliothèque privée de l'utilisateur actuellement authentifié. L'ensemble complet des URI utilisés pour chaque opération acceptée dans l'API est résumé dans la documentation de référence de l'API Livres.

Voici quelques exemples de la façon dont cela fonctionne dans l'API Livres.

Effectuez une recherche sur le matelassage:

GET https://www.googleapis.com/books/v1/volumes?q=quilting

Obtenez des informations sur le volume s1gVAAAAYAAJ:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

REST à partir de JavaScript

Vous pouvez appeler l'API Livres à l'aide de REST à partir de JavaScript (également appelé JSON-P), en utilisant le paramètre de requête callback et une fonction de rappel. Cela vous permet de développer des applications enrichies qui affichent des données Livres sans écrire de code côté serveur.

Remarque:Vous pouvez appeler des méthodes authentifiées en transmettant un jeton OAuth 2.0 à l'aide du paramètre access_token. Pour obtenir un jeton OAuth 2.0 à utiliser avec JavaScript, suivez les instructions décrites dans OAuth 2.0 pour les applications Web côté client. Dans l'onglet "Accès à l'API" de la console des API, veillez à configurer un ID client pour les applications Web et à utiliser ces identifiants OAuth 2.0 pour obtenir votre jeton.

L'exemple suivant utilise cette approche pour afficher les résultats de recherche pour "harry potter":

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

Format des données

JSON

JSON (JavaScript Object Notation) est un format de données qui ne dépend pas d'un langage et qui fournit une représentation textuelle simple de structures de données arbitraires. Pour en savoir plus, accédez à json.org.