Vamos começar

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.

O Google oferece um conjunto de estantes predefinidas para cada usuário:

  • 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.

Estantes de livros de exemplo:

  • "Favoritos"
    • "Harry Potter"
  • "Meus e-books"
    • "Alternar"
    • "Crepúsculo"
    • "A garota com a tatuagem de dragão"

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).