Como começar

Neste documento, você encontra detalhes sobre o conhecimento básico necessário para usar a API Google Books.

  1. Introdução
  2. Antes de começar
    1. Criar uma Conta do Google
    2. Conheça o Google Livros
    3. Saiba mais sobre como autorizar solicitações e identificar seu aplicativo
  3. Contexto da API Books
    1. Conceitos sobre livros
    2. Modelo de dados da API Books
    3. Operações da API Books
  4. Estilo de chamada
    1. REST
  5. Formato de dados
    1. JSON

Introdução

Este documento é destinado aos desenvolvedores que querem criar aplicativos que possam interagir com a API Google Books. O Google Livros tem a visão de digitalizar os livros do mundo. É possível 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á tem uma conta de teste, então está tudo pronto. Acesse a interface do usuário do Google Livros para configurar, editar ou visualizar os dados de teste.

Conhecer o Google Livros

Se você não conhece os conceitos do Google Livros, leia este documento e teste a interface do usuário antes de começar a programar. Para acompanhar este documento, você precisa conhecer conceitos de programação e formatos de dados da Web.

Saiba mais sobre como autorizar solicitações e identificar seu aplicativo

Quando seu aplicativo solicita dados privados, a solicitação tem que 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 privadas 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 o 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 obter 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.

Informações sobre a API Books

Conceitos de livros

O Google Livros é baseado em quatro conceitos básicos:

  • Volume: representa os dados que o Google Livros hospeda sobre um livro ou uma revista. É o principal recurso da API Books. Todos os outros recursos dessa API contêm ou anotam um volume.
  • Bookshelf: uma estante de livros é uma coleção de volumes. O Google Livros oferece um conjunto de estantes predefinidas para cada usuário. Algumas delas são totalmente gerenciadas pelo usuário, algumas preenchidas automaticamente com base na atividade do usuário e outras mistas. Os usuários podem criar, modificar ou excluir outras estantes, que são sempre preenchidas manualmente com volumes. As estantes podem ser privadas ou públicas pelo usuário.

    Observação:atualmente, a criação e a exclusão de estantes, bem como a modificação das configurações de privacidade delas, só podem ser feitas no site do Google Livros.

  • Avaliação: a avaliação de um volume é uma combinação de nota 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 adequadamente.
  • 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 nunca abriu esse volume antes, a posição de leitura não existe. A posição de leitura pode armazenar informações detalhadas de posição até a resolução de uma palavra. Essas informações são sempre particulares do 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 Bookshelf: representa uma única estante para 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. Dessa forma, não é possível listar todos os recursos de volume, mas é possível listar todos os volumes que correspondem a um conjunto de termos de pesquisa.
Coleção de estantes de livros
Uma coleção de estantes de livros consiste em todos os recursos de estante gerenciados pelo Google Livros. As estantes devem sempre ser referenciadas no contexto da biblioteca de um usuário específico. As estantes podem conter zero ou mais volumes.

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

  • Favoritos: estante 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 mutável.
  • Lendo agora: estante mutável.
  • Leitura: estante mutável.
  • Revisado: preenchido com os volumes que o usuário revisou. O usuário não pode adicionar ou remover volumes manualmente.
  • Acesso recente: preenchido com os volumes que o usuário abriu recentemente em um leitor Web. O usuário não pode adicionar volumes manualmente.
  • Meus e-books: estante mutável. Os livros comprados são adicionados automaticamente, mas podem ser removidos de forma manual.
  • Livros para você: repleto de recomendações de volume personalizadas. Se não tivermos recomendações para o usuário, essa estante não existirá.

Exemplos de estantes:

  • "Favoritos"
    • "Harry Potter"
  • "Meus e-books"
    • "Alternar"
    • "Crepúsculo"
    • "A Garota com a Tatuagem do 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 específico de recursos em uma coleção. GET em um URI de coleta.
inserir Insere um novo recurso em uma coleção (criando um novo recurso). POST em um URI de coleta, em que 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, em que você transmite dados para o recurso atualizado.
excluir Exclui um recurso específico. DELETE no URI do recurso, em que você transmite os dados do recurso a ser 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 "Minha biblioteca" e todas exigem autenticação.

Tipo de recurso
Operações suportadas
lista inserir obter atualizar excluir
Volumes sim* sim
Estantes sim* sim, AUTENTICADO sim* sim, AUTENTICADO sim, AUTENTICADO
Leitura de 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 solicitações não autenticadas operam somente em dados públicos.

Como chamar estilos

Há várias maneiras de invocar a API:

  • Usando REST diretamente
  • Usar REST a partir do JavaScript (sem necessidade de 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 é o seguinte:

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

em que resourceID é o identificador de um volume ou recurso de estante e parameters são qualquer parâmetro a ser aplicado à consulta. Consulte a Referência de parâmetros de consulta para mais detalhes.

O formato das extensões de caminho resourceID permite identificar o recurso em que você está operando 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
...

Observe que as operações com mylibrary no URI se aplicam apenas aos dados da biblioteca privada do usuário autenticado no momento. O conjunto completo de URIs usados para cada operação compatível na API é resumido no documento Referência da API Books.

Aqui estão alguns exemplos de como isso funciona na API Books.

Pesquise "quilting":

GET https://www.googleapis.com/books/v1/volumes?q=quilting

Receba 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 a partir de JavaScript (também chamado de JSON-P), usando o parâmetro de consulta callback e uma função de callback. Isso permite que você desenvolva aplicativos avançados que exibam dados de Livros sem escrever códigos no lado do servidor.

Observação:você pode chamar métodos autenticados transmitindo um token OAuth 2.0 com o parâmetro access_token. Para obter um token OAuth 2.0 para uso 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, configure um ID de cliente para aplicativos da Web e use 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).