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

Premiers pas

Ce document détaille 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 écrire des applications pouvant interagir avec l'API Google Livres. Google Livres a pour ambition de numériser les livres du monde entier. Vous pouvez utiliser l'API Google Livres pour rechercher du contenu, organiser et modifier la bibliothèque personnelle d'un utilisateur authentifié.

Avant de commencer

Créer un compte Google

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

Se familiariser avec les livres

Si vous ne connaissez pas les concepts de Google Livres, nous vous invitons à lire ce document et à 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 de la section "Ma bibliothèque" dans l'API Google Livres sont considérées comme privées et nécessitent une authentification et une autorisation. En outre, toute opération qui modifie les données de 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 demande n'a pas besoin d'être autorisée, mais elle doit être accompagnée d'un identifiant, comme une clé API.

Pour savoir comment autoriser des requêtes et utiliser des clés API, consultez Autoriser les requêtes et identifier votre application dans le document "Utiliser l'API".

Arrière-plan de l'API Livres

Concepts des livres

Google Livres repose sur quatre concepts de base:

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 Livres. Toutes les autres ressources de cette API contiennent ou annotent un volume.
Étagère : 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 certaines sont mixtes. Les utilisateurs peuvent créer, modifier ou supprimer d'autres étagères, qui sont toujours remplies de volumes manuellement. Les étagères peuvent être rendues privées ou publiques par l'utilisateur.
Remarque : Pour le moment, vous ne pouvez créer et supprimer des étagères, ni modifier les paramètres de confidentialité des étagères que via le site Google Livres.
Review : un avis sur un volume est une combinaison de note et/ou de texte. Un utilisateur peut envoyer un avis par volume. Les avis sont également disponibles à partir de sources externes et sont correctement attribués.
Position de lecture : une position de lecture indique la dernière position de lecture d'un volume pour un utilisateur. Un utilisateur ne peut avoir qu'une seule position de lecture par volume. Si l'utilisateur n'a pas encore ouvert ce volume, 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 privées.

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

Une ressource est une entité de données individuelle dotée d'un identifiant unique. L'API Livres fonctionne sur deux types de ressources basés sur les concepts décrits ci-dessus:

Volume resource (Volume) : représente un volume.
Ressource Bookshelf: 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:

Collecter le volume: La collection de volumes regroupe toutes les ressources de volume gérées par Google Livres. Vous ne pouvez donc 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 d'étagères comprend toutes les ressources Bookshelf 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 zéro, un ou plusieurs volumes.

Opérations de l'API Livres

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

Operations	Description	Mappages HTTP REST
list	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
obtenir	Récupère une ressource spécifique.	`GET` sur l'URI de la ressource.
mettre à jour	Met à jour une ressource spécifique.	`PUT` sur l'URI de la ressource, où vous transmettez les données de 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.

Les opérations disponibles pour les différents types de ressources sont récapitulées dans le tableau ci-dessous. 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 acceptées
	liste	insérer	get	mise à jour	supprimer
Volumes	oui*		oui
Étagères	oui*	oui, AUTHENTICATED	oui*	oui, AUTHENTICATED	oui, AUTHENTICATED
Lire les positions		oui, AUTHENTICATED	oui, AUTHENTICATED	oui, AUTHENTICATED	oui, AUTHENTICATED

*Les versions AUTHENTICATED et non authentifiées de ces opérations sont toutes deux disponibles. Les requêtes authentifiées fonctionnent sur les données privées "Ma bibliothèque" de l'utilisateur, tandis que les requêtes non authentifiées ne fonctionnent que sur des données publiques.

Styles d'appel

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

Utiliser directement REST
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. Elle spécifie une ressource par un URI 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 de 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 pour les URI de l'API Livres est le suivant:

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

où resourceID est l'identifiant d'un volume ou d'une ressource "bookshelf", et parameters correspond aux 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 sur laquelle vous travaillez, 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 avec mylibrary dans l'URI ne s'appliquent qu'aux données de la bibliothèque privée de l'utilisateur actuellement authentifié. L'ensemble complet des URI utilisés pour chaque opération compatible avec l'API est récapitulé dans la documentation de référence de l'API Livres.

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

Rechercher 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 d'écrire des applications enrichies qui affichent des données Google 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 API" de la console des API, veillez à configurer un ID client pour les applications Web et à utiliser ces identifiants OAuth 2.0 lorsque vous obtenez 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.