En este documento, se detalla el conocimiento previo que necesitas para utilizar la API de Google Libros.
Introducción
Este documento está dirigido a desarrolladores que deseen escribir aplicaciones que puedan interactuar con la API de Google Books. Google Libros tiene la visión de digitalizar libros de todo el mundo. Puedes usar la API de Google Libros para buscar contenido, organizar la biblioteca personal de un usuario autenticado y también modificarla.
Antes de comenzar
Obtener una Cuenta de Google
Para realizar pruebas, necesitas una Cuenta de Google. Si ya tienes una cuenta de prueba, no necesitas hacer nada más. Puedes visitar la interfaz de usuario de Google Libros para configurar, editar o ver tus datos de prueba.
Familiarízate con los libros
Si no estás familiarizado con los conceptos de Google Libros, te recomendamos leer este documento y experimentar con la interfaz de usuario antes de comenzar a programar. En este documento, se supone que estás familiarizado con los conceptos de programación web y los formatos de datos web.
Más información sobre la autorización de solicitudes y la identificación de tu aplicación
Cuando tu aplicación solicita datos privados, la solicitud debe estar autorizada por un usuario autenticado que tenga acceso a esa información.
En particular, todas las operaciones que se encuentran en "Mi biblioteca" en la API de Google Books se consideran privadas y requieren autenticación y autorización. Además, solo el usuario propietario de esos datos puede realizar cualquier operación que modifique datos de Google Libros.
Cuando tu aplicación solicita datos públicos, no es necesario autorizar la solicitud, pero debe ir acompañada de un identificador, como una clave de API.
Para obtener información sobre cómo autorizar solicitudes y usar claves de API, consulta Cómo autorizar solicitudes y cómo identificar tu aplicación en el documento Cómo usar la API.
Fondo de la API de Books
Conceptos de libros
Google Libros se basa en cuatro conceptos básicos:
- Volumen: Representa los datos que Google Libros aloja sobre un libro o una revista. Es el recurso principal de la API de Books. Todos los demás recursos de esta API contienen o anotan un volumen.
- Bookshelf: Una biblioteca es una colección de volúmenes. Google Libros proporciona un conjunto de estanterías predefinidas para cada usuario. Algunas de ellas son completamente administradas por el usuario, otras se completan automáticamente según la actividad del usuario y otras son mixtas. Los usuarios pueden crear, modificar o borrar otras estanterías, que siempre se llenan de volúmenes de forma manual. El usuario puede hacer que las estanterías sean privadas o públicas.
Nota: Por el momento, solo se pueden crear y borrar estanterías, y modificar la configuración de privacidad de las estanterías, a través del sitio de Google Libros.
- Opinión: La opinión de un volumen es una combinación de una calificación por estrellas o un texto. Los usuarios pueden enviar una opinión por volumen. Las opiniones también están disponibles de fuentes externas y se atribuyen de forma adecuada.
- Posición de lectura: Una posición de lectura indica la última posición de lectura de un volumen para un usuario. Un usuario solo puede tener una posición de lectura por volumen. Si el usuario no abrió ese volumen antes, la posición de lectura no existe. La posición de lectura puede almacenar información detallada de la posición hasta la resolución de una palabra. Esta información siempre es privada para el usuario.
Modelo de datos de la API de Libros
Un recurso es una entidad de datos individual con un identificador único. La API de Libros funciona con dos tipos de recursos, según los conceptos descritos anteriormente:
- Recurso de volumen: Representa un volumen.
- Recurso de Bookshelf: Representa una biblioteca única para un usuario en particular.
El modelo de datos de la API de Libros se basa en grupos de recursos llamados colecciones:
- Recopilación de volúmenes
- La colección de volúmenes es una colección de cada recurso de volumen que administra Google Libros.
Por lo tanto, no puedes enumerar todos los recursos de volumen, pero puedes enumerar todos los volúmenes que coincidan con un conjunto de términos de búsqueda.
- Colección de libros
- Una colección de estanterías consta de todos los recursos de estanterías que administra Google Libros. Siempre se debe hacer referencia a las estanterías en el contexto de la biblioteca de un usuario específico. Las estanterías pueden contener cero o más volúmenes.
- Favoritos: Estantería mutable
- Comprado: Se propaga con los volúmenes que compró el usuario. El usuario no puede agregar ni quitar volúmenes de forma manual.
- Para leer: Estantería mutable
- Leyendo ahora: Estantería mutable
- Leer: Estantería mutable
- Revisado: Se propaga con los volúmenes sobre los que opinó el usuario. El usuario no puede agregar ni quitar volúmenes de forma manual.
- Visto recientemente: Se propaga con los volúmenes que el usuario abrió recientemente en un lector web. El usuario no puede agregar volúmenes de forma manual.
- Mis libros electrónicos: biblioteca mutable Los libros comprados se agregan automáticamente, pero se pueden quitar de forma manual.
- Libros para ti: Se propagan con recomendaciones de volumen personalizadas. Si no tenemos recomendaciones para el usuario, significa que esta estantería no existe.
- "Favoritos"
- "Harry Potter"
- "Mis libros electrónicos"
- "Cambiar"
- "Crepúsculo"
- “La chica del dragón tatuado”
Google proporciona un conjunto de estanterías predefinidas para cada usuario:
Estantes de ejemplo:
Operaciones de la API de Libros
Puedes invocar cinco métodos diferentes en las colecciones y los recursos de la API de Libros, como se describe en la siguiente tabla.
| Operación | Descripción | Asignaciones de HTTP de REST |
|---|---|---|
| list | Muestra una lista de un subconjunto específico de recursos dentro de una colección. | GET en un URI de colección |
| insertar | Inserta un recurso nuevo en una colección (crea un recurso nuevo). | POST en un URI de colección, en el que pasas datos para un recurso nuevo |
| get | Obtiene un recurso específico. | GET en el URI del recurso |
| actualización | Actualiza un recurso específico. | PUT en el URI del recurso, donde pasas los datos para el recurso actualizado. |
| borrar | Borra un recurso específico. | DELETE en el URI de recurso, donde pasas datos para que el recurso se borre. |
Las operaciones compatibles con los distintos tipos de recursos se resumen en la siguiente tabla. Las operaciones que se aplican a los datos privados de un usuario se denominan operaciones "Mi biblioteca" y todas requieren autenticación.
Tipo de recurso |
Operaciones admitidas |
||||
|---|---|---|---|---|---|
| lista | insertar | obtener | actualización | borrar | |
| Volúmenes | sí* | sí | |||
| Estanterías | sí* | sí, AUTENTICACIÓN | sí* | sí, AUTENTICACIÓN | sí, AUTENTICACIÓN |
| Cómo leer las posiciones | sí, AUTENTICACIÓN | sí, AUTENTICACIÓN | sí, AUTENTICACIÓN | sí, AUTENTICACIÓN | |
*Las versiones AUTHENTICATED y no autenticadas de estas operaciones están disponibles, en las que las solicitudes autenticadas operan en los datos privados de “Mi biblioteca” del usuario y las solicitudes no autenticadas operan solo en datos públicos.
Estilos de llamada
Hay varias formas de invocar la API:
- Usa REST directamente
- Cómo usar REST desde JavaScript (no se requiere código del servidor)
REST
REST es un estilo de arquitectura de software que proporciona un enfoque conveniente y coherente para solicitar y modificar datos.
El término REST es el acrónimo en inglés de "Transferencia de estado representacional". En el contexto de las API de Google, se refiere al uso de verbos HTTP para recuperar y modificar representaciones de los datos que almacena Google.
En un sistema RESTful, los recursos se almacenan en un almacén de datos; un cliente envía una solicitud para que el servidor ejecute una acción en particular (como crear, recuperar, actualizar o borrar un recurso) y el servidor ejecuta la acción y envía una respuesta que, por lo general, es una representación del recurso especificado.
En las APIs de RESTful de Google, el cliente especifica una acción con un verbo HTTP, como POST, GET, PUT o DELETE. Especifica un recurso mediante un URI único a nivel global con la siguiente forma:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
Dado que todos los recursos de API tienen URI únicos accesibles a través de HTTP, REST permite el almacenamiento de datos en caché y está optimizado para funcionar con la infraestructura distribuida de la Web.
Puedes encontrar las definiciones de métodos en la documentación de estándares del HTTP 1.1, los que incluyen especificaciones para GET, POST, PUT y DELETE.
REST en la API de Libros
Las operaciones de Libros compatibles se asignan directamente a los verbos HTTP de REST, como se describe en Operaciones de la API de Libros.
El formato específico para los URI de la API de Books es el siguiente:
https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters
donde resourceID es el identificador de un volumen o un recurso de estantería, y parameters son cualquier parámetro que se aplique a la consulta. Consulta la Referencia de parámetros de consulta para obtener más detalles.
El formato de las extensiones de ruta resourceID te permite identificar el recurso que estás ejecutando actualmente, por ejemplo:
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 ...
Ten en cuenta que las operaciones con mylibrary en el URI solo se aplican a los datos de la biblioteca privada del usuario autenticado actualmente. El conjunto completo de URI que se usa para cada operación compatible en la API se resume en el documento Referencia de la API de Libros.
Estos son algunos ejemplos de cómo funciona esto en la API de Books.
Realiza una búsqueda de acolchados:
GET https://www.googleapis.com/books/v1/volumes?q=quilting
Obtén información sobre el volumen s1gVAAAAYAAJ:
GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ
REST desde JavaScript
Puedes invocar la API de Libros con REST de JavaScript (también llamado JSON-P), mediante el parámetro de consulta callback y una función de devolución de llamada. Esto te permite escribir aplicaciones enriquecidas que muestran datos de Libros sin escribir ningún código del servidor.
Nota: Para llamar a los métodos autenticados, pasa un token de OAuth 2.0 con el parámetro access_token. Si deseas obtener un token de OAuth 2.0 para usarlo con JavaScript, sigue las instrucciones que se describen en OAuth 2.0 para aplicaciones web del cliente. En la pestaña "Acceso a la API" de la Consola de API, asegúrate de configurar un ID de cliente para las aplicaciones web y de utilizar esas credenciales de OAuth 2.0 al obtener tu token.
En el siguiente ejemplo, se usa este enfoque para mostrar los resultados de la búsqueda de "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>
Formato de los datos
JSON
JSON (JavaScript Object Notation) es un formato de datos común y, también, independiente del lenguaje que proporciona una representación de texto simple de estructuras de datos arbitrarias. Para obtener más información, visita json.org.