Halaman ini diterjemahkan oleh Cloud Translation API.

Memulai

Dokumen ini menjelaskan pengetahuan latar belakang yang Anda perlukan untuk menggunakan Google Books API.

Pengantar
Sebelum memulai
Latar belakang Books API
Gaya panggilan
1. REST
Format data
1. JSON

Pengantar

Dokumen ini ditujukan bagi developer yang ingin menulis aplikasi yang dapat berinteraksi dengan Google Books API. Google Buku memiliki visi untuk mendigitalkan buku-buku di dunia. Anda dapat menggunakan Google Books API untuk menelusuri konten, mengatur koleksi pribadi pengguna yang diautentikasi, dan juga memodifikasinya.

Sebelum memulai

Buat Akun Google

Anda memerlukan Akun Google untuk tujuan pengujian. Jika sudah memiliki akun pengujian, berarti Anda sudah siap; Anda dapat mengunjungi antarmuka pengguna Google Buku untuk menyiapkan, mengedit, atau melihat data pengujian.

Berkenalan dengan Buku

Jika belum memahami konsep Google Buku, Anda harus membaca dokumen ini dan bereksperimen dengan antarmuka pengguna sebelum mulai membuat kode. Dokumen ini mengasumsikan bahwa Anda sudah memahami konsep pemrograman web dan format data web.

Pelajari cara mengizinkan permintaan dan mengidentifikasi aplikasi Anda

Saat aplikasi Anda meminta data pribadi, permintaan itu harus diizinkan oleh pengguna terautentikasi yang memiliki akses ke data tersebut.

Secara khusus, semua operasi pada "Koleksiku" di Google Books API dianggap pribadi dan memerlukan autentikasi serta otorisasi. Selain itu, operasi apa pun yang mengubah data Google Buku hanya dapat dilakukan oleh pengguna yang memiliki data tersebut.

Ketika aplikasi Anda meminta data publik, permintaan ini tidak perlu diotorisasi, tetapi harus disertai dengan ID, seperti kunci API.

Untuk informasi tentang cara mengizinkan permintaan dan menggunakan kunci API, lihat Memberi otorisasi permintaan dan mengidentifikasi aplikasi di dokumen Menggunakan API.

Latar belakang Books API

Konsep buku

Google Buku dibuat berdasarkan empat konsep dasar:

Volume: Volume mewakili data yang dihosting Google Buku tentang buku atau majalah. Ini adalah resource utama di Books API. Semua resource lain dalam API ini berisi atau menganotasi volume.
Bookshelf: Rak buku adalah koleksi volume. Google Buku menyediakan sekumpulan rak buku yang telah ditetapkan sebelumnya untuk setiap pengguna, yang beberapa di antaranya dikelola sepenuhnya oleh pengguna, beberapa di antaranya diisi secara otomatis berdasarkan aktivitas pengguna, dan beberapa di antaranya digabungkan. Pengguna dapat membuat, mengubah, atau menghapus rak buku lain, yang selalu diisi dengan volume secara manual. Rak buku dapat dijadikan pribadi atau publik oleh pengguna.
Catatan: Membuat dan menghapus rak buku serta mengubah setelan privasi di rak buku saat ini hanya dapat dilakukan melalui situs Google Buku.
Ulasan: Ulasan volume adalah kombinasi dari rating bintang dan/atau teks. Pengguna dapat mengirim satu ulasan per volume. Ulasan juga tersedia dari sumber luar dan diatribusikan dengan tepat.
Posisi Membaca: Posisi membaca menunjukkan posisi pembacaan terakhir dalam volume untuk pengguna. Pengguna hanya dapat memiliki satu posisi membaca per volume. Jika pengguna belum pernah membuka volume tersebut sebelumnya, posisi membaca tidak ada. Posisi membaca dapat menyimpan informasi posisi terperinci hingga ke resolusi kata. Informasi ini selalu bersifat pribadi bagi pengguna.

Model data Books API

Resource adalah entity data individual dengan ID unik. Books API beroperasi pada dua jenis resource, berdasarkan konsep yang dijelaskan di atas:

Resource volume: Menunjukkan volume.
Resource rak buku: Mewakili satu rak buku untuk pengguna tertentu.

Model data Books API didasarkan pada grup resource, yang disebut koleksi:

Pengumpulan volume: Koleksi volume, adalah kumpulan setiap resource volume yang dikelola oleh Google Buku. Dengan demikian, Anda tidak dapat mencantumkan semua resource volume, tetapi Anda dapat mencantumkan semua volume yang cocok dengan sekumpulan istilah penelusuran.
Koleksi rak buku: Koleksi rak buku terdiri dari semua materi rak buku yang dikelola oleh Google Buku. Rak buku harus selalu dirujuk dalam konteks koleksi pengguna tertentu. Rak buku dapat berisi nol volume atau lebih.

Operasi Books API

Anda dapat memanggil lima metode berbeda pada koleksi dan resource di Books API, seperti yang dijelaskan dalam tabel berikut.

Operasi	Deskripsi	Pemetaan HTTP REST
list	Mencantumkan subset resource yang ditentukan dalam koleksi.	`GET` pada URI koleksi.
sisipkan	Menyisipkan resource baru ke dalam koleksi (membuat resource baru).	`POST` di URI koleksi, tempat Anda meneruskan data untuk resource baru.
dapatkan	Mendapatkan resource tertentu.	`GET` pada URI resource.
info terbaru	Memperbarui resource tertentu.	`PUT` pada URI resource, tempat Anda meneruskan data untuk resource yang diupdate.
hapus	Menghapus resource tertentu.	`DELETE` pada URI resource, tempat Anda meneruskan data untuk resource yang akan dihapus.

Operasi yang didukung untuk berbagai jenis resource dirangkum dalam tabel di bawah. Operasi yang berlaku untuk data pribadi pengguna disebut operasi "Library Saya", dan semuanya memerlukan autentikasi.

Jenis Resource	Operasi yang Didukung
	daftar	sisipkan	dapatkan	info terbaru	hapus
Volume	ya*		ya
Rak buku	ya*	ya, AUTENTIKASI	ya*	ya, AUTENTIKASI	ya, AUTENTIKASI
Posisi Membaca		ya, AUTENTIKASI	ya, AUTENTIKASI	ya, AUTENTIKASI	ya, AUTENTIKASI

*Versi operasi AUTHENTICATED maupun yang tidak diautentikasi tersedia, sementara permintaan yang diautentikasi beroperasi pada data "My Library" pribadi pengguna, sedangkan permintaan yang tidak diautentikasi hanya beroperasi pada data publik.

Gaya panggilan

Ada beberapa cara untuk memanggil API:

Menggunakan REST secara langsung
Menggunakan REST dari JavaScript (kode sisi server tidak diperlukan)

REST

REST adalah gaya arsitektur software yang memberikan pendekatan yang praktis dan konsisten untuk meminta dan memodifikasi data.

Istilah REST adalah singkatan dari "Representational State Transfer". Dalam konteks Google API, hal ini mengacu pada penggunaan kata kerja HTTP untuk mengambil dan mengubah representasi data yang disimpan oleh Google.

Dalam sistem RESTful, resource disimpan di penyimpanan data; klien mengirim permintaan agar server melakukan tindakan tertentu (seperti membuat, mengambil, memperbarui, atau menghapus resource), dan server melakukan tindakan dan mengirim respons, sering kali dalam bentuk representasi resource yang ditentukan.

Di RESTful API Google, klien menentukan tindakan menggunakan kata kerja HTTP seperti POST, GET, PUT, atau DELETE. Ini menetapkan resource melalui URI yang unik secara global dengan bentuk berikut:

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

Karena semua resource API memiliki URI unik yang dapat diakses HTTP, REST memungkinkan caching data dan dioptimalkan untuk berfungsi dengan infrastruktur terdistribusi web.

Anda dapat memperoleh manfaat dari definisi metode dalam dokumentasi standar HTTP 1.1; dokumentasi tersebut menyertakan spesifikasi untuk GET, POST, PUT, dan DELETE.

REST di Books API

Operasi Buku yang didukung dipetakan langsung ke kata kerja HTTP REST, seperti yang dijelaskan dalam operasi Books API.

Format spesifik untuk URI Books API adalah:

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

dengan resourceID adalah ID untuk resource volume atau rak buku, dan parameters adalah parameter apa pun yang akan diterapkan pada kueri. Lihat Referensi parameter kueri untuk mengetahui detailnya.

Format ekstensi jalur resourceID memungkinkan Anda mengidentifikasi resource yang Anda gunakan saat ini, misalnya:

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

Perlu diperhatikan bahwa operasi dengan mylibrary dalam URI hanya berlaku untuk data library pribadi pengguna yang saat ini diautentikasi. Kumpulan lengkap URI yang digunakan untuk setiap operasi yang didukung dalam API diringkas dalam dokumen Referensi Books API.

Berikut beberapa contoh cara kerjanya di Books API.

Lakukan penelusuran untuk quilting:

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

Dapatkan informasi tentang volume s1gVAAAAYAAJ:

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

REST dari JavaScript

Anda dapat memanggil Books API menggunakan REST dari JavaScript (disebut juga JSON-P), menggunakan parameter kueri callback dan fungsi callback. Hal ini memungkinkan Anda menulis aplikasi kaya yang menampilkan data Buku tanpa menulis kode sisi server apa pun.

Catatan: Anda dapat memanggil metode yang diautentikasi dengan meneruskan token OAuth 2.0 menggunakan parameter access_token. Untuk mendapatkan token OAuth 2.0 untuk digunakan dengan JavaScript, ikuti petunjuk yang dijelaskan di OAuth 2.0 untuk aplikasi web sisi klien. Pada tab "Akses API" di Konsol API, pastikan Anda telah menyiapkan Client ID untuk aplikasi web, dan menggunakan kredensial OAuth 2.0 tersebut saat mendapatkan token.

Contoh berikut menggunakan pendekatan ini dalam menampilkan hasil penelusuran untuk "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>

Format data

JSON

JSON (JavaScript Object Notation) adalah format data umum independen bahasa yang memberikan representasi teks sederhana untuk struktur data arbitrer. Untuk informasi selengkapnya, lihat json.org.