Como começar

Este documento detalha o conhecimento básico necessário para usar a API Google Books.

Introdução
Antes de começar
Informações básicas sobre a API Books
Estilo de chamada
1. REST
Formato de dados
1. JSON

Introdução

Este documento é destinado a desenvolvedores que querem criar aplicativos que interajam com a API Google Books. O Google Livros tem como objetivo digitalizar os livros do mundo. É possível usar a API Google Books para pesquisar conteúdo, organizar e modificar a biblioteca pessoal de um usuário autenticado.

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, tudo pronto. Acesse a interface do usuário do Google Livros para configurar, editar ou visualizar seus dados de teste.

Conheça 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 codificar. Para seguir este documento, é necessário ter familiaridade com os conceitos de programação e formatos de dados da Web.

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

Em particular, 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 só pode ser realizada pelo usuário proprietário desses dados.

No caso dos 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 Autorizar solicitações e identificar seu aplicativo no documento "Como usar a API".

Informações básicas 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 nesta 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, outras são preenchidas automaticamente com base na atividade do usuário, e outras são mistas. Os usuários podem criar, modificar ou excluir outras estantes, que são sempre preenchidas com volumes manualmente. As estantes podem ser definidas como privadas ou públicas pelo usuário.
Observação:no momento, só é possível criar e excluir estantes, além de modificar as configurações de privacidade delas, pelo site do Google Livros.
Avaliação: é uma combinação de uma nota por estrelas e/ou texto. Um usuário pode enviar uma avaliação por volume. As avaliações também estão disponíveis em fontes externas e são atribuídas corretamente.
Posição de leitura: indica a última posição lida em um volume por 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 vai existir. 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 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 "Estante": 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:

Volume Collection: A coleção de volumes é um conjunto 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 correspondem a um conjunto de termos de pesquisa.
Coleção da estante: Uma coleção de estante consiste em todos os recursos de estante gerenciados pelo Google Books. As estantes precisam sempre ser referenciadas no contexto da biblioteca de um usuário específico. As estantes podem conter zero ou mais volumes.

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, 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.
delete	Exclui um recurso específico.	`DELETE` no URI do recurso, em que você transmite dados para o 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 exigem autenticação.

Tipo de recurso	Operações suportadas
	list	insert	get	update	delete
Volumes	sim*		sim
Estantes	sim*	sim, AUTHENTICATED	sim*	sim, AUTHENTICATED	sim, AUTHENTICATED
Posições de leitura		sim, AUTHENTICATED	sim, AUTHENTICATED	sim, AUTHENTICATED	sim, AUTHENTICATED

*As versões AUTENTICADAS e não autenticadas dessas operações estão disponíveis. As solicitações autenticadas operam nos dados particulares do usuário em "Minha biblioteca", e as não autenticadas operam apenas em dados públicos.

Como chamar estilos

Há várias maneiras de invocar a API:

Usar REST diretamente
Usar REST em 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 abreviação de "Representational State Transfer (Transferência de Estado Representacional)". 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, uma ação é especificada no cliente usando um verbo HTTP como POST, GET, PUT ou DELETE. Um recurso é definido por meio de um URI global 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 compatíveis do Google Books 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 volume ou recurso de estante de livros, e parameters são parâmetros a serem aplicados à consulta. Consulte 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á trabalhando. 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 apenas aos dados da biblioteca particular do usuário autenticado no momento. O conjunto completo de URIs usados para cada operação compatível na API está resumido no documento de referência da API Books.

Confira alguns exemplos de como isso funciona na API Books.

Pesquise "quilting":

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

Receber 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 REST em JavaScript (também chamado de JSON-P), usando o parâmetro de consulta callback e uma função de callback. Isso permite escrever aplicativos avançados que mostram dados do Google Livros sem escrever código do lado do servidor.

Observação:é possível chamar métodos autenticados transmitindo um token OAuth 2.0 usando o parâmetro access_token. Para receber 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 do 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 mostrar resultados da pesquisa por "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).

Como começar Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.