Premiers pas

Ce document décrit les connaissances de base dont vous avez besoin pour utiliser l'API Google Books.

Introduction
Avant de commencer
Contexte de l'API Books
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 objectif de numériser les livres du monde entier. Vous pouvez utiliser l'API Google Books 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 possédez déjà un compte de test, vous n'avez rien d'autre à faire. Vous pouvez accéder à l'interface utilisateur de Google Livres pour configurer, modifier ou afficher vos données de test.

Se familiariser avec Livres

Si vous n'êtes pas familiarisé avec les concepts de Google Livres, nous vous recommandons de lire ce document et d'essayer 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 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 qui possède ces données.

Lorsque votre application demande des données publiques, la requête 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 les requêtes et utiliser les clés API, consultez Autoriser les requêtes et identifier votre application dans le document "Utiliser l'API".

Contexte de l'API Books

Concepts relatifs aux livres

Google Livres repose sur quatre concepts fondamentaux :

Volume : un volume représente les données hébergées par Google Livres concernant un livre ou 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 bibliothèque est une collection de volumes. Google Livres fournit un ensemble de bibliothèques prédéfinies pour chaque utilisateur. Certaines sont entièrement gérées par l'utilisateur, d'autres sont remplies automatiquement en fonction de son activité et d'autres sont mixtes. Les utilisateurs peuvent créer, modifier ou supprimer d'autres bibliothèques, qui sont toujours remplies manuellement. Les utilisateurs peuvent rendre leurs bibliothèques privées ou publiques.
Remarque : Pour le moment, vous ne pouvez créer et supprimer des bibliothèques, ni modifier leurs paramètres de confidentialité, que sur le site Google Livres.
Avis : un avis sur un livre est une combinaison d'une note en étoiles et/ou d'un texte. Un utilisateur peut envoyer un avis par volume. Des avis provenant de sources externes sont également disponibles et sont attribués de manière appropriée.
Position de lecture : indique la dernière position de lecture d'un utilisateur dans un volume. Un utilisateur ne peut avoir qu'une seule position de lecture par volume. Si l'utilisateur n'a jamais ouvert ce volume, la position de lecture n'existe pas. La position de lecture peut stocker des informations détaillées sur la position, jusqu'à la résolution d'un mot. Ces informations sont toujours privées pour l'utilisateur.

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

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

Ressource Volume : représente un volume.
Ressource Bookshelf : représente une seule bibliothèque pour un utilisateur spécifique.

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

Collection de volumes: La collection de volumes est une collection de toutes les ressources de volume gérées par Google Livres. Par conséquent, vous ne pouvez pas lister toutes les ressources de volume, mais vous pouvez lister tous les volumes qui correspondent à un ensemble de termes de recherche.
Collection Bookshelf: Une collection d'étagères se compose de toutes les ressources d'étagères gérées par Google Livres. Les bibliothèques doivent toujours être référencées dans le contexte de la bibliothèque d'un utilisateur spécifique. Les bibliothèques peuvent contenir zéro ou plusieurs volumes.

Opérations de l'API Books

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

Opération	Description	Mappages HTTP REST
liste	Liste un sous-ensemble spécifié de ressources dans une collection.	`GET` sur un URI de collection.
insérer	Insère une 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	Obtient une ressource spécifique.	`GET` sur l'URI de la ressource.
update	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 les données de 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 opérations "Ma bibliothèque". Elles nécessitent toutes une authentification.

Type de ressource	Opérations compatibles
	list	insert	get	update	delete
Volumes	oui*		oui
Bibliothèques	oui*	Oui, AUTHENTIFIÉ	oui*	Oui, AUTHENTIFIÉ	Oui, AUTHENTIFIÉ
Positions de lecture		Oui, AUTHENTIFIÉ	Oui, AUTHENTIFIÉ	Oui, AUTHENTIFIÉ	Oui, AUTHENTIFIÉ

*Les versions AUTHENTICATED et non authentifiées de ces opérations sont disponibles. Les requêtes authentifiées fonctionnent sur les données privées de l'utilisateur dans "Ma bibliothèque", tandis que les requêtes non authentifiées ne fonctionnent 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

REST est 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'architecture utilisant des verbes HTTP pour récupérer et modifier les représentations des 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 comme POST, GET, PUT ou DELETE. La ressource est désignée 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 Books

Les opérations Books compatibles sont directement mappées aux verbes HTTP REST, comme décrit dans Opérations de l'API Books.

Le format spécifique des URI de l'API Books 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 correspond à 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 d'accès resourceID vous permet d'identifier la ressource sur laquelle vous travaillez actuellement. 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 Books.

Voici quelques exemples de fonctionnement dans l'API Books.

Effectuez une recherche sur le quilting :

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 Books à 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 riches qui affichent des données Books 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 aux API" de la console APIs, 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.

Premiers pas Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.