Este documento detalha o conhecimento prévio necessário para usar a API Google Books.
Introdução
Este documento é destinado a desenvolvedores que desejam criar aplicativos que possam interagir com a API Google Books. O Google Livros tem uma visão para digitalizar os livros do mundo. Você pode usar a API Google Books para pesquisar conteúdo, organizar a biblioteca pessoal de um usuário autenticado e modificá-la.
Antes de começar
Crie uma Conta do Google
Você precisa de uma Conta do Google para fins de teste. Se você já tiver uma conta de teste, está tudo pronto. Acesse a interface de usuário do Google Livros para configurar, editar ou visualizar os dados de teste.
Conheça o Livros
Se você não estiver familiarizado com os conceitos do Google Livros, leia este documento e teste a interface do usuário antes de começar a programar. Ele pressupõe que você esteja familiarizado com conceitos de programação e formatos de dados da Web.
Saiba mais sobre como autorizar solicitações e identificar o aplicativo
Quando seu aplicativo solicita dados privados, a solicitação precisa ser autorizada por um usuário autenticado com acesso a esses dados.
Especificamente, todas as operações em "Minha biblioteca" na API Google Books são consideradas particulares e exigem autenticação e autorização. Além disso, qualquer operação que modifique dados do Google Livros pode ser realizada apenas pelo usuário proprietário desses dados.
Quando seu aplicativo solicita dados públicos, a solicitação não precisa ser autorizada, mas precisa ser acompanhada por um identificador, como uma chave de API.
Para informações sobre como autorizar solicitações e usar chaves de API, consulte Como autorizar solicitações e identificar seu aplicativo no documento Como usar a API.
Histórico da API Books
Conceitos de livros
O Google Livros é baseado em quatro conceitos básicos:
- Volume: um volume representa os dados hospedados pelo Google Livros sobre um livro ou uma revista. É o principal recurso da API Books. Todos os outros recursos nessa API contêm ou anotam um volume.
- Estante: uma estante é uma coleção de volumes. O Google Livros
oferece um conjunto de estantes predefinidas para cada usuário, algumas são
totalmente gerenciadas pelo usuário, algumas são preenchidas automaticamente
com base na atividade do usuário e outras são combinadas. Os usuários podem criar,
modificar ou excluir outras estantes, que são sempre preenchidas com volumes
manualmente. As estantes podem ser privadas ou públicas pelo usuário.
Observação: no momento, a criação e a exclusão de estantes, assim como a modificação das configurações de privacidade nelas só podem ser feitas no site do Google Livros.
- Avaliação: a avaliação de um volume é uma combinação de avaliação com estrelas e/ou texto. Um usuário pode enviar uma avaliação por volume. As avaliações também estão disponíveis de fontes externas e são atribuídas corretamente.
- Posição de leitura: indica a última posição de leitura em um volume para um usuário. Um usuário só pode ter uma posição de leitura por volume. Se o usuário não tiver aberto esse volume antes, a posição de leitura não existirá. A posição de leitura pode armazenar informações detalhadas até a resolução de uma palavra. Essas informações são sempre particulares para o usuário.
Modelo de dados da API Books
Um recurso é uma entidade individual de dados com um identificador exclusivo. A API Books opera em dois tipos de recursos, com base nos conceitos descritos acima:
- Recurso de volume: representa um volume.
- Recurso de estante: representa uma única estante de um usuário específico.
O modelo de dados da API Books é baseado em grupos de recursos, chamados de coleções:
- Coleta de volume
- A coleção de volumes é uma coleção de todos os recursos de volume gerenciados pelo Google Livros.
Por isso, não é possível listar todos os recursos de volume, mas é possível listar todos os volumes que correspondam a um conjunto de termos de pesquisa.
- Coleção de estante
- Uma coleção de estantes consiste em todos os recursos de estantes gerenciados pelo Google Livros. As estantes precisam sempre ser referenciadas no contexto da biblioteca de um usuário específico. As estantes podem conter zero ou mais volumes.
- Favoritos: estante de livros mutável.
- Comprado: preenchido com os volumes que o usuário comprou. O usuário não pode adicionar ou remover volumes manualmente.
- Para ler: estante de livros mutável.
- Leitura agora: estante de livros mutável.
- Ler: estante de livros mutável.
- Revisado: preenchido com volumes que o usuário analisou. O usuário não pode adicionar ou remover volumes manualmente.
- Visualizados recentemente: preenchidos por volumes que o usuário abriu recentemente em um leitor da Web. O usuário não pode adicionar volumes manualmente.
- Meus e-books: estante de livros mutável. Os livros comprados são adicionados automaticamente, mas podem ser removidos manualmente.
- Livros para você: preenchido com recomendações de volume personalizadas. Se não tivermos recomendações para o usuário, essa estante não existe.
- "Favoritos"
- "Harry Potter"
- "Meus e-books"
- "Alternar"
- "Crepúsculo"
- "A garota com a tatuagem de dragão"
O Google oferece um conjunto de estantes predefinidas para cada usuário:
Estantes de livros de exemplo:
Operações da API Books
É possível invocar cinco métodos diferentes em coleções e recursos na API Books, conforme descrito na tabela a seguir.
Operação | Descrição | Mapeamentos HTTP REST |
---|---|---|
list | Lista um subconjunto especificado de recursos em uma coleção. | GET em um URI de coleção. |
inserir | Insere um novo recurso em uma coleção (criando um novo recurso). | POST em um URI de coleção, onde você transmite dados para um novo recurso. |
get | Recebe um recurso específico. | GET no URI do recurso. |
update | Atualiza um recurso específico. | PUT no URI do recurso, onde você transmite dados para o recurso atualizado. |
delete | Exclui um recurso específico. | DELETE no URI do recurso, em que você transmite dados para que o recurso seja excluído. |
As operações compatíveis com os vários tipos de recursos estão resumidas na tabela abaixo. As operações que se aplicam aos dados particulares de um usuário são chamadas de operações "Minha biblioteca" e todas exigem autenticação.
Tipo de recurso |
Operações suportadas |
||||
---|---|---|---|---|---|
lista | inserir | get | atualizar | excluir | |
Volumes | sim* | sim | |||
Estantes | sim* | sim, AUTENTICADO | sim* | sim, AUTENTICADO | sim, AUTENTICADO |
Como ler posições | sim, AUTENTICADO | sim, AUTENTICADO | sim, AUTENTICADO | sim, AUTENTICADO |
*As versões AUTHENTICATED e não autenticadas dessas operações estão disponíveis, em que as solicitações autenticadas operam nos dados particulares de "Minha biblioteca" do usuário, e as não autenticadas operam somente em dados públicos.
Como chamar estilos
Há várias maneiras de invocar a API:
- Usando REST diretamente
- Usar o REST do JavaScript (não é necessário um código do lado do servidor)
REST
REST é um estilo de arquitetura de software que fornece uma abordagem conveniente e consistente para solicitar e modificar dados.
O termo REST é a sigla de "Representational State Transfer". No contexto das APIs do Google, ele se refere ao uso de verbos HTTP para recuperar e modificar representações de dados armazenados pelo Google.
Em um sistema RESTful, os recursos são mantidos em um armazenamento de dados. Um cliente envia uma solicitação para que uma ação específica seja executada no servidor, como a criação, recuperação, atualização ou exclusão de um recurso. Essa ação é executada e uma resposta é enviada, geralmente no formato de uma representação do recurso especificado.
Nas APIs RESTful do Google, o cliente especifica uma ação usando um verbo HTTP, como POST
, GET
, PUT
ou DELETE
. Ele especifica um recurso por um URI globalmente exclusivo no seguinte formato:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
Como todos os recursos da API têm URIs exclusivos acessíveis por HTTP, a REST permite o armazenamento em cache dos dados e é otimizada para funcionar na infraestrutura distribuída da Web.
As definições de método (em inglês) encontradas na documentação dos padrões HTTP 1.1 podem ser úteis. Nelas estão incluídas as especificações GET
, POST
, PUT
e DELETE
.
REST na API Books
As operações do Books compatíveis são mapeadas diretamente para verbos HTTP REST, conforme descrito em Operações da API Books.
O formato específico dos URIs da API Books é:
https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters
em que resourceID
é o identificador de um recurso
de volume ou estante e parameters
são
qualquer parâmetro a ser aplicado à consulta. Consulte a referência de parâmetros de consulta para ver mais detalhes.
O formato das extensões de caminho resourceID
permite identificar o recurso em operação no momento, por exemplo:
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 ...
As operações com mylibrary
no URI se aplicam somente aos
dados da biblioteca particular do usuário autenticado no momento. O conjunto completo de URIs usados em cada operação compatível na API é resumido no documento Referência da API Books.
Veja alguns exemplos de como isso funciona na API Books.
Faça uma pesquisa por quilting:
GET https://www.googleapis.com/books/v1/volumes?q=quilting
Veja informações sobre o volume s1gVAAAAYAAJ:
GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ
REST a partir de JavaScript
É possível invocar a API Books usando o REST do JavaScript, também chamado de JSON-P, com o parâmetro de consulta callback
e uma função de callback. Isso permite que você grave aplicativos avançados que exibem dados de livros sem escrever código do servidor.
Observação: é possível chamar métodos autenticados transmitindo um token do OAuth 2.0 usando o parâmetro access_token
. Para ter um token OAuth 2.0 para usar com JavaScript, siga as instruções descritas em OAuth 2.0 para aplicativos da Web do lado do cliente. Na guia "Acesso à API" do Console de APIs, não se esqueça de configurar um ID do cliente para aplicativos da Web e de usar essas credenciais do OAuth 2.0 ao receber seu token.
O exemplo a seguir usa essa abordagem para exibir resultados da pesquisa para "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 dados
JSON
JSON (JavaScript Object Notation) é um formato de dados comum e independente de linguagem que oferece uma representação de texto simples das estruturas de dados arbitrárias. Para mais informações, acesse json.org (em inglês).