Per iniziare

Questo documento descrive le conoscenze di base necessarie per utilizzare l'API Google Books.

Introduzione
Prima di iniziare
Informazioni di base sull'API Books
Stile di chiamata
1. REST
Formato dei dati
1. JSON

Introduzione

Questo documento è destinato agli sviluppatori che vogliono scrivere applicazioni che possono interagire con l'API Google Books. Google Libri ha l'obiettivo di digitalizzare i libri del mondo. Puoi utilizzare l'API Google Books per cercare contenuti, organizzare e modificare la raccolta personale di un utente autenticato.

Prima di iniziare

Creare un Account Google

Per i test, devi avere un Account Google. Se hai già un account di prova, non devi fare altro. Puoi visitare l'interfaccia utente di Google Libri per configurare, modificare o visualizzare i dati di prova.

Acquisire familiarità con Libri

Se non hai familiarità con i concetti di Google Libri, ti consigliamo di leggere questo documento e di fare pratica con l'interfaccia utente prima di iniziare a scrivere codice. Questo documento presuppone che tu abbia familiarità con i concetti di programmazione web e con i formati dei dati web.

Scopri di più sull'autorizzazione delle richieste e sull'identificazione della tua applicazione

Quando la tua applicazione richiede dati privati, la richiesta deve essere autorizzata da un utente autenticato che ha accesso a tali dati.

In particolare, tutte le operazioni nella sezione "La mia raccolta" dell'API Google Books sono considerate private e richiedono autenticazione e autorizzazione. Inoltre, qualsiasi operazione che modifichi i dati di Google Libri può essere eseguita solo dall'utente proprietario dei dati.

Quando la tua applicazione richiede dati pubblici, la richiesta non deve essere autorizzata, ma deve essere accompagnata da un identificatore, ad esempio una chiave API.

Per informazioni su come autorizzare le richieste e utilizzare le chiavi API, consulta la sezione Autorizzazione delle richieste e identificazione dell'applicazione nel documento Utilizzo dell'API.

Background dell'API Books

Concetti di Google Libri

Google Libri si basa su quattro concetti fondamentali:

Volume: un volume rappresenta i dati ospitati da Google Libri su un libro o una rivista. È la risorsa principale dell'API Books. Tutte le altre risorse di questa API contengono o annotano un volume.
Scaffale: uno scaffale è una raccolta di volumi. Google Libri fornisce un insieme di librerie predefinite per ogni utente, alcune delle quali sono completamente gestite dall'utente, altre vengono compilate automaticamente in base all'attività dell'utente e altre ancora sono miste. Gli utenti possono creare, modificare o eliminare altre librerie, che vengono sempre riempite con i volumi manualmente. Le librerie possono essere rese private o pubbliche dall'utente.
Nota: la creazione e l'eliminazione di librerie, nonché la modifica delle impostazioni della privacy delle librerie, possono essere eseguite al momento solo tramite il sito Google Libri.
Recensione: una recensione di un volume è una combinazione di una valutazione a stelle e/o testo. Un utente può inviare una recensione per volume. Sono disponibili anche recensioni provenienti da fonti esterne, a cui viene attribuita la giusta attribuzione.
Posizione di lettura: indica l'ultima posizione di lettura di un volume per un utente. Un utente può avere una sola posizione di lettura per volume. Se l'utente non ha mai aperto il volume, la posizione di lettura non esiste. Il punto di lettura può memorizzare informazioni dettagliate sulla posizione fino alla risoluzione di una parola. Queste informazioni sono sempre private per l'utente.

Modello di dati dell'API Books

Una risorsa è una singola entità di dati con un identificatore univoco. L'API Books opera su due tipi di risorse, in base ai concetti descritti sopra:

Risorsa volume: rappresenta un volume.
Risorsa Libreria: rappresenta una singola libreria per un determinato utente.

Il modello di dati dell'API Books si basa su gruppi di risorse, chiamati raccolte:

Volume Collection: La raccolta di volumi è una raccolta di ogni risorsa volume gestita da Google Libri. Pertanto, non puoi elencare tutte le risorse di volumi, ma puoi elencare tutti i volumi che corrispondono a un insieme di termini di ricerca.
Raccolta di scaffali: Una raccolta di scaffali è costituita da tutte le risorse dello scaffale gestite da Google Libri. I ripiani devono sempre essere citati nel contesto della raccolta di un utente specifico. Le librerie possono contenere zero o più volumi.

Operazioni dell'API Books

Puoi richiamare cinque metodi diversi su raccolte e risorse nell'API Books, come descritto nella tabella seguente.

Operazione	Descrizione	Mapping HTTP REST
list	Elenca un sottoinsieme specificato di risorse all'interno di una raccolta.	`GET` su un URI di raccolta.
insert	Inserisce una nuova risorsa in una raccolta (creando una nuova risorsa).	`POST` su un URI di raccolta, in cui trasmetti i dati per una nuova risorsa.
get	Recupera una risorsa specifica.	`GET` sull'URI risorsa.
aggiornamento	Aggiorna una risorsa specifica.	`PUT` sull'URI della risorsa, in cui trasmetti i dati per la risorsa aggiornata.
elimina	Elimina una risorsa specifica.	`DELETE` nell'URI della risorsa, dove trasmetti i dati della risorsa da eliminare.

Le operazioni supportate per i vari tipi di risorse sono riepilogate nella tabella seguente. Le operazioni che si applicano ai dati privati di un utente sono chiamate operazioni "La mia raccolta " e richiedono tutte l'autenticazione.

Tipo di risorsa	Operazioni supportate
	list	insert	get	update	delete
Volumi	sì*		sì
Librerie	sì*	Sì, AUTENTICATO	sì*	Sì, AUTENTICATO	Sì, AUTENTICATO
Posizioni di lettura		Sì, AUTENTICATO	Sì, AUTENTICATO	Sì, AUTENTICATO	Sì, AUTENTICATO

*Sono disponibili sia le versioni AUTENTICATE che quelle non autenticate di queste operazioni, in cui le richieste autenticate operano sui dati privati "La mia raccolta " dell'utente e le richieste non autenticate operano solo sui dati pubblici.

Stili di chiamata

Esistono diversi modi per richiamare l'API:

Utilizzo diretto di REST
Utilizzo di REST da JavaScript (non è necessario codice lato server)

REST

REST è un tipo di architettura software che fornisce un approccio pratico e coerente per la richiesta e la modifica dei dati.

Il termine REST è l'acronimo di "REpresentational State Transfer". Nel contesto delle API di Google, si riferisce all'utilizzo dei verbi HTTP per recuperare e modificare le rappresentazioni dei dati archiviati da Google.

In un sistema RESTful, le risorse vengono archiviate in un datastore. Un client invia una richiesta affinché il server esegua una determinata azione (ad esempio la creazione, il recupero, l'aggiornamento o l'eliminazione di una risorsa) e il server esegue l'azione e invia una risposta, spesso sotto forma di rappresentazione della risorsa specificata.

Nelle API RESTful di Google, il client specifica un'azione mediante un verbo HTTP come POST, GET, PUT o DELETE. La risorsa viene specificata tramite un URI globalmente univoco con il seguente formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Poiché tutte le risorse dell'API dispongono di URI univoci accessibili tramite HTTP, REST consente la memorizzazione dei dati nella cache ed è ottimizzato per operare con l'infrastruttura distribuita del web.

Potrebbero esserti utili le definizioni dei metodi riportate nella documentazione degli standard HTTP 1.1, in cui sono incluse le specifiche per i metodi GET, POST, PUT e DELETE.

REST nell'API Books

Le operazioni di Books supportate corrispondono direttamente ai verbi HTTP in REST, come descritto in Operazioni dell'API Books.

Il formato specifico per gli URI dell'API Books è:

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

dove resourceID è l'identificatore di una risorsa volume o libreria e parameters sono i parametri da applicare alla query. Per ulteriori dettagli, consulta la sezione Riferimento ai parametri di query.

Il formato delle estensioni del percorso resourceID ti consente di identificare la risorsa su cui stai operando, ad esempio:

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

Tieni presente che le operazioni con mylibrary nell'URI si applicano solo ai dati della raccolta privata dell'utente attualmente autenticato. Il set completo di URI utilizzati per ogni operazione supportata nell'API è riepilogato nel documento Riferimento API Books.

Ecco un paio di esempi di come funziona nell'API Books.

Esegui una ricerca di trapuntatura:

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

Ottieni informazioni sul volume s1gVAAAAYAAJ:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

REST da JavaScript

Puoi richiamare l'API Books utilizzando REST da JavaScript (chiamato anche JSON-P), utilizzando il parametro di query callback e una funzione di callback. Ciò ti consente di scrivere applicazioni avanzate che mostrano i dati di Books senza scrivere codice lato server.

Nota:puoi chiamare metodi autenticati passando un token OAuth 2.0 utilizzando il parametro access_token. Per ottenere un token OAuth 2.0 da utilizzare con JavaScript, segui le istruzioni descritte in OAuth 2.0 per applicazioni web lato client. Nella scheda "Accesso API" della console API, assicurati di configurare un ID client per le applicazioni web e di utilizzare queste credenziali OAuth 2.0 quando ottieni il token.

L'esempio seguente utilizza questo approccio per visualizzare i risultati di ricerca per "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 dei dati

JSON

JSON (JavaScript Object Notation) è un formato di dati comune, indipendente dal linguaggio, che fornisce una semplice rappresentazione testuale di strutture arbitrarie di dati. Per ulteriori informazioni, visita il sito json.org.

Per iniziare Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.