Memulai

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

  1. Pengantar
  2. Sebelum memulai
    1. Buat Akun Google
    2. Mengenal Buku
    3. Pelajari cara mengizinkan permintaan dan mengidentifikasi aplikasi Anda
  3. Latar belakang Books API
    1. Konsep buku
    2. Model data Books API
    3. Operasi Books API
  4. Gaya panggilan
    1. REST
  5. 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 mengubahnya juga.

Sebelum memulai

Dapatkan Akun Google

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

Memahami Buku

Jika tidak memahami konsep Google Buku, Anda harus membaca dokumen ini dan bereksperimen dengan antarmuka pengguna sebelum memulai coding. Dokumen ini mengasumsikan bahwa Anda telah 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.

Khususnya, semua operasi pada "My Library" di Google Books API dianggap bersifat pribadi dan memerlukan autentikasi serta otorisasi. Selain itu, operasi apa pun yang memodifikasi data Google Buku hanya dapat dilakukan oleh pengguna yang memiliki data tersebut.

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

Untuk mendapatkan informasi tentang cara mengizinkan permintaan dan menggunakan kunci API, lihat Mengizinkan permintaan dan mengidentifikasi aplikasi Anda di dokumen Menggunakan API.

Latar belakang Books API

Konsep buku

Google Buku dibuat berdasarkan empat konsep dasar:

  • Volume: Volume merepresentasikan data yang dihosting Google Buku tentang buku atau majalah. API ini adalah resource utama di Books API. Semua resource lain dalam API ini berisi atau menganotasi volume.
  • Rak buku: Rak buku adalah kumpulan volume. Google Buku menyediakan kumpulan rak buku standar untuk setiap pengguna, yang sebagian di antaranya dikelola sepenuhnya oleh pengguna, dan beberapa di antaranya diisi secara otomatis berdasarkan aktivitas pengguna, dan beberapa di antaranya tercampur. 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 memodifikasi 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 mengirimkan satu ulasan per volume. Ulasan juga tersedia dari luar sumber 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, posisi membaca tidak akan ada. Posisi membaca dapat menyimpan informasi posisi yang mendetail hingga resolusi kata. Informasi ini selalu bersifat pribadi bagi pengguna.

Model data Books API

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

  • Resource volume: Merepresentasikan volume.
  • Resource rak buku: Mewakili satu rak buku untuk pengguna tertentu.

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

Pengumpulan volume
Pengumpulan volume, adalah koleksi 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 resource rak buku yang dikelola oleh Google Buku. Rak buku harus selalu dirujuk dalam konteks perpustakaan pengguna tertentu. Rak buku dapat berisi nol volume atau lebih.

Google menyediakan serangkaian rak buku standar untuk setiap pengguna:

  • Favorit: Rak buku yang dapat diubah.
  • Dibeli: Diisi dengan volume yang telah dibeli pengguna. Pengguna tidak dapat menambahkan atau menghapus volume secara manual.
  • Untuk Dibaca: Rak buku yang dapat diubah.
  • Baca Sekarang: Rak buku yang dapat diubah.
  • Telah Dibaca: Rak buku yang dapat diubah.
  • Ditinjau: Diisi dengan volume yang telah ditinjau pengguna. Pengguna tidak dapat menambahkan atau menghapus volume secara manual.
  • Baru Dilihat: Diisi dengan volume yang baru-baru ini dibuka pengguna di pembaca web. Pengguna tidak dapat menambahkan volume secara manual.
  • eBook Saya: Rak buku yang bisa berubah. Buku yang dibeli akan otomatis ditambahkan, tetapi dapat dihapus secara manual.
  • Buku Untuk Anda: Diisi dengan rekomendasi volume yang dipersonalisasi. Jika tidak ada rekomendasi untuk pengguna, rak buku ini tidak akan ada.

Contoh rak buku:

  • "Favorit"
    • "Harry Potter"
  • "eBook Saya"
    • "Alihkan"
    • "Twilight"
    • "Gadis dengan Tato Naga"

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 tertentu dalam koleksi. GET pada URI koleksi.
masukkan Menyisipkan resource baru ke dalam koleksi (membuat resource baru). POST pada URI koleksi, tempat Anda meneruskan data untuk resource baru.
dapatkan Mendapatkan resource tertentu. GET pada URI resource.
perbarui Memperbarui resource tertentu. PUT pada URI resource, tempat Anda meneruskan data untuk resource yang diperbarui.
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 dengan operasi "Koleksi Saya", dan semuanya memerlukan autentikasi.

Jenis Resource
Operasi yang Didukung
daftar masukkan dapatkan pembaruan hapus
Volume ya* ya
Rak buku ya* ya, AUTENTIKASI ya* ya, AUTENTIKASI ya, AUTENTIKASI
Posisi Membaca ya, AUTENTIKASI ya, AUTENTIKASI ya, AUTENTIKASI ya, AUTENTIKASI

*Tersedia versi AUTHENTICATED dan tidak terautentikasi dari operasi ini, ketika permintaan yang diautentikasi tidak beroperasi pada data "My Library" pribadi pengguna, dan 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 (tidak perlu kode sisi server)

REST

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

Istilah REST adalah singkatan dari "Representational State Transfer". Dalam konteks Google API, merujuk pada penggunaan kata kerja HTTP untuk mengambil dan memodifikasi 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 serta 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. Instance ini menentukan resource berdasarkan 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.

Sebaiknya lihat definisi metode dalam dokumentasi standar HTTP 1.1; definisi tersebut mencakup 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 sebagai ID untuk resource volume atau rak buku, dan parameters adalah parameter apa pun yang akan diterapkan ke kueri. Lihat Referensi parameter kueri untuk mengetahui detailnya.

Format ekstensi jalur resourceID memungkinkan Anda mengidentifikasi resource yang sedang Anda operasikan, 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
...

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

Berikut adalah beberapa contoh cara kerjanya di Books API.

Lakukan penelusuran untuk selimut:

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 (juga disebut JSON-P), menggunakan parameter kueri callback dan fungsi callback. Ini memungkinkan Anda menulis aplikasi lengkap yang menampilkan data Buku tanpa harus menulis kode sisi server apa pun.

Catatan: Anda dapat memanggil metode yang diautentikasi dengan meneruskan token OAuth 2.0 menggunakan parameter access_token. Guna 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 menyiapkan Client ID untuk aplikasi web, dan menggunakan kredensial OAuth 2.0 saat mendapatkan token.

Contoh berikut menggunakan pendekatan ini untuk 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 mendapatkan informasi lebih lanjut, lihat json.org.