Başlayın

Bu belgede, Google Books API'yi kullanmak için ihtiyacınız olan arka plan bilgileri ayrıntılı bir şekilde açıklanmaktadır.

  1. Giriş
  2. Başlamadan önce
    1. Google Hesabı edinin
    2. Kitaplar'ı tanıma
    3. İstekleri yetkilendirme ve uygulamanızı tanımlama hakkında bilgi edinin.
  3. Books API arka planı
    1. Google Kitaplar kavramları
    2. Books API veri modeli
    3. Books API işlemleri
  4. Arama stili
    1. REST
  5. Veri biçimi
    1. JSON

Giriş

Bu belge, Google Books API ile etkileşimde bulunabilecek uygulamalar yazmak isteyen geliştiricilere yöneliktir. Google Kitaplar dünyadaki kitapları dijitalleştirme konusunda bir vizyona sahip. İçerik aramak, kimliği doğrulanmış bir kullanıcının kişisel kitaplığını düzenlemek ve bu kitaplıkta değişiklik yapmak için Google Books API'yi kullanabilirsiniz.

Başlamadan önce

Bir Google Hesabı edinin

Test amacıyla bir Google Hesabı'na ihtiyacınız vardır. Hâlihazırda bir test hesabınız varsa hazırsınız demektir. Test verilerinizi ayarlamak, düzenlemek veya görüntülemek için Google Kitaplar kullanıcı arayüzünü ziyaret edebilirsiniz.

Kitaplar'ı daha yakından tanıyın

Google Kitaplar kavramlarına aşina değilseniz bu dokümanı okumalı ve kodlamaya başlamadan önce kullanıcı arayüzü ile denemeler yapmalısınız. Bu belgede, web programlama kavramlarına ve web veri biçimlerine aşina olduğunuz varsayılır.

İstekleri yetkilendirme ve uygulamanızı tanımlama hakkında bilgi edinin

Uygulamanız gizli veri isteğinde bulunduğunda isteğin, söz konusu verilere erişimi olan kimliği doğrulanmış bir kullanıcı tarafından yetkilendirilmesi gerekir.

Özellikle, Google Books API'de "Kitaplığım" altında bulunan tüm işlemler gizli olarak kabul edilir ve kimlik doğrulama ile yetkilendirme gerektirir. Ayrıca Google Kitaplar verilerinde değişiklik yapan tüm işlemler, yalnızca söz konusu verilerin sahibi olan kullanıcı tarafından gerçekleştirilebilir.

Uygulamanız herkese açık veri isteğinde bulunduğunda, isteğin yetkilendirilmesi gerekmez ancak istekle birlikte API anahtarı gibi bir tanımlayıcının eklenmesi gerekir.

İstekleri nasıl yetkilendireceğiniz ve API anahtarlarını nasıl kullanacağınız hakkında bilgi edinmek için API'yi kullanma dokümanındaki İstekleri yetkilendirme ve uygulamanızı tanımlama bölümüne bakın.

Kitaplar API'sı arka planı

Kitaplarla ilgili kavramlar

Google Kitaplar dört temel kavram üzerine kurulmuştur:

  • Cilt: Cilt, Google Kitaplar'ın bir kitap veya dergi hakkında barındırdığı verileri temsil eder. Books API'deki birincil kaynaktır. Bu API'deki diğer tüm kaynaklar bir birim içerir veya birim açıklama ekler.
  • Bookshelf: Kitaplık, ciltlerden oluşan bir koleksiyondur. Google Kitaplar, her kullanıcı için önceden tanımlanmış bir dizi kitap rafı sağlar. Bunların bazıları tamamen kullanıcı tarafından yönetilir. Bu kitaplıklardan bazıları kullanıcının etkinliğine göre otomatik olarak doldurulur ve bazıları da bir arada bulunur. Kullanıcılar, her zaman manuel olarak ciltlerle doldurulan diğer kitap raflarını oluşturabilir, değiştirebilir veya silebilir. Kitaplıklar kullanıcı tarafından özel veya herkese açık hale getirilebilir.

    Not: Kitap rafları oluşturma, silme ve kitap raflarındaki gizlilik ayarlarını değiştirme işlemlerini şu anda yalnızca Google Kitaplar sitesi üzerinden yapabilirsiniz.

  • Yorum: Bir ciltle ilgili yorum, yıldız puanı ve/veya metinden oluşan bir kombinasyondur. Kullanıcılar her cilt için bir yorum gönderebilir. Yorumlar, dış kaynaklardan da edinilebilir ve uygun şekilde ilişkilendirilir.
  • Okuma Konumu: Okuma konumu, bir kitaptaki kullanıcının son okunma konumunu belirtir. Bir kullanıcının her cilt için yalnızca bir okuma konumu olabilir. Kullanıcı bu cildi daha önce açmadıysa okuma konumu mevcut değildir. Okuma konumu, ayrıntılı konum bilgilerini bir kelimenin çözünürlüğüne kadar depolayabilir. Bu bilgi her zaman kullanıcıya özeldir.

Kitaplar API'sı veri modeli

Kaynak, benzersiz bir tanımlayıcıya sahip bağımsız bir veri varlığıdır. Books API, yukarıda açıklanan kavramlara göre iki tür kaynak üzerinde çalışır:

  • Hacim kaynağı: Bir hacmi temsil eder.
  • Kitap rafı kaynağı: Belirli bir kullanıcıya ait tek bir kitaplığı temsil eder.

Books API veri modeli, koleksiyon adı verilen kaynak gruplarını temel alır:

Cilt koleksiyonu
Cilt koleksiyonu, Google Kitaplar tarafından yönetilen her cilt kaynağından oluşan bir koleksiyondur. Bu nedenle, tüm hacim kaynaklarını listeleyemezsiniz ancak bir dizi arama terimiyle eşleşen tüm hacimleri listeleyebilirsiniz.
Kitap rafı koleksiyonu
Kitaplık koleksiyonu, Google Kitaplar tarafından yönetilen tüm kitap rafı kaynaklarından oluşur. Kitap raflarına her zaman belirli bir kullanıcının kitaplığı bağlamında atıfta bulunulmalıdır. Kitaplıklarda sıfır veya daha fazla cilt bulunabilir.

Google, her kullanıcı için önceden tanımlanmış bir dizi kitap rafı sağlar:

  • Favoriler: Değişebilir kitap rafı.
  • Satın alındı: Kullanıcının satın aldığı ciltlerle doldurulur. Kullanıcılar manuel olarak birim ekleyemez veya kaldıramaz.
  • Okunacak: Değişebilir kitap rafı.
  • Şimdi Okuyanlar: Değişebilir kitap rafı.
  • Okumuşum: Değişebilir kitap rafı.
  • İncelendi: Kullanıcının incelediği ciltlerle doldurulur. Kullanıcılar manuel olarak birim ekleyemez veya kaldıramaz.
  • Son Görüntülenenler: Kullanıcının bir web okuyucusunda son açtığı ciltlerle doldurulur. Kullanıcı manuel olarak birim ekleyemez.
  • E-Kitaplarım: Değişebilir kitap rafı. Satın alınan kitaplar otomatik olarak eklenir ancak manuel olarak kaldırılabilir.
  • Sizin İçin Kitaplar: Kişiselleştirilmiş cilt önerileriyle doldurulur. Kullanıcı için herhangi bir önerimiz yoksa bu kitap rafı mevcut değildir.

Örnek kitap rafları:

  • "Favoriler"
    • "Harry Potter"
  • "e-Kitaplarım"
    • "Değiştir"
    • "Twilight"
    • "Ejderha Dövmesi Yapan Kız"

Books API işlemleri

Aşağıdaki tabloda açıklandığı gibi, Books API'deki koleksiyonlar ve kaynaklarla ilgili beş farklı yöntemi çağırabilirsiniz.

İşlem Açıklama REST HTTP eşlemeleri
list Bir koleksiyondaki kaynakların belirli bir alt kümesini listeler. Koleksiyon URI'sında GET.
ekle Bir koleksiyona yeni kaynak ekler (yeni kaynak oluşturma). Yeni kaynak için verileri aktardığınız koleksiyon URI'sında POST.
al Belirli bir kaynağı alır. Kaynak URI'da GET.
güncelle Belirli bir kaynağı günceller. Kaynak URI'da PUT. Burada, güncellenen kaynak için verileri iletebilirsiniz.
sil Belirli bir kaynağı siler. Silinecek kaynağın verilerini aktardığınız kaynak URI'sinde DELETE.

Çeşitli kaynak türleri için desteklenen işlemler aşağıdaki tabloda özetlenmiştir. Kullanıcının gizli verileri için geçerli olan işlemlere "Kitaplığım" işlemleri denir ve bunların tümü için kimlik doğrulama gerekir.

Kaynak Türü
Desteklenen İşlemler
liste ekle alın güncelleme sil
Ciltler evet* evet
Kitap rafları evet* evet, KİMLİK DOĞRULANMIŞ evet* evet, KİMLİK DOĞRULANMIŞ evet, KİMLİK DOĞRULANMIŞ
Okuma Konumları evet, KİMLİK DOĞRULANMIŞ evet, KİMLİK DOĞRULANMIŞ evet, KİMLİK DOĞRULANMIŞ evet, KİMLİK DOĞRULANMIŞ

*Bu işlemlerin hem AUTHENTICATED hem de kimliği doğrulanmamış sürümleri kullanılabilir. Burada, kimliği doğrulanmış istekler kullanıcının gizli "Kitaplığım" verileri üzerinde çalışır. Kimliği doğrulanmayan istekler ise yalnızca herkese açık veriler üzerinde çalışır.

Arama stilleri

API'yi çağırmanın birkaç yolu vardır:

  • Doğrudan REST kullanma
  • JavaScript'ten REST kullanma (sunucu tarafı koda gerek yoktur)

REST

REST, veri isteme ve değiştirmeye kullanışlı ve tutarlı yaklaşım sağlayan bir yazılım mimarisi stilidir.

REST terimi, "Representational State Transfer"in (Temsili Durum Aktarımı) kısaltmasıdır. Google API'leri bağlamında, Google tarafından saklanan verilerin temsillerini almak ve değiştirmek için HTTP fiillerini kullanma anlamına gelir.

RESTful bir sistemde, kaynaklar bir veri deposunda saklanır. Bir istemci, sunucunun belirli bir işlemi (ör. kaynak oluşturma, alma, güncelleme veya silme) gerçekleştirmesi için istek gönderir. Sunucu, işlemi gerçekleştirir ve yanıt gönderir. Bu yanıt genelde belirtilen kaynağın bir temsili biçimindedir.

Google'ın RESTful API'lerinde istemci, bir işlemi HTTP fiili kullanarak (ör. POST, GET, PUT veya DELETE) belirtir. Bir kaynağı, aşağıdaki biçimdeki küresel olarak benzersiz bir URI ile belirtir:

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

Tüm API kaynaklarının HTTP tarafından erişilebilen benzersiz URI'ları olduğu için REST, veri önbelleğe almayı etkinleştirir ve web'deki dağıtılan altyapıyla birlikte çalışmak üzere optimize edilmiştir.

HTTP 1.1 standartları belgelerindeki yöntem tanımlarını yararlı bulabilirsiniz. Bu tanımlar, GET, POST, PUT ve DELETE özelliklerini içerir.

Books API'de REST

Desteklenen Kitaplar işlemleri, Books API işlemleri bölümünde açıklandığı gibi doğrudan REST HTTP fiilleriyle eşlenir.

Books API URI'leri için özel biçim şu şekildedir:

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

Burada resourceID bir hacim veya kitap rafı kaynağının tanımlayıcısı, parameters ise sorguya uygulanacak parametrelerdir. Ayrıntılar için Sorgu parametresi referansı bölümüne bakın.

resourceID yol uzantılarının biçimi, şu anda üzerinde çalıştığınız kaynağı belirlemenize olanak tanır. Örneğin:

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

URI'da mylibrary ile yapılan işlemlerin, yalnızca kimliği doğrulanmış olan kullanıcının gizli kitaplık verilerine uygulandığını unutmayın. API'de desteklenen her işlem için kullanılan URI'ların tam grubu Books API Reference (Kitaplar API Referansı) belgesinde özetlenmiştir.

Aşağıda, bu sürecin Books API'de nasıl işlediğine dair birkaç örnek verilmiştir.

Yorgan için bir arama yapın:

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

s1gVAAAAYAAJ hacmi hakkında bilgi alın:

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

JavaScript'ten REST

Books API'yi, callback sorgu parametresi ve geri çağırma işleviyle JavaScript'ten REST (JSON-P olarak da adlandırılır) kullanarak çağırabilirsiniz. Bu, herhangi bir sunucu tarafı kodu yazmadan Kitaplar verilerini görüntüleyen zengin uygulamalar yazmanıza olanak sağlar.

Not: access_token parametresini kullanıp OAuth 2.0 jetonu ileterek kimliği doğrulanmış yöntemleri çağırabilirsiniz. JavaScript ile kullanmak üzere bir OAuth 2.0 jetonu almak için İstemci tarafı web uygulamaları için OAuth 2.0 başlıklı makalede açıklanan talimatları uygulayın. API Konsolu'nun "API Erişimi" sekmesinde, web uygulamaları için bir İstemci Kimliği ayarladığınızdan ve jetonunuzu alırken bu OAuth 2.0 kimlik bilgilerini kullandığınızdan emin olun.

Aşağıdaki örnekte "harry potter" için arama sonuçlarını görüntülemek üzere bu yaklaşım kullanılmaktadır:

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

Veri biçimi

JSON

JSON (JavaScript Object Notation - JavaScript Nesne Gösterimi), rastgele veri yapılarının basit metin temsilini sağlayan yaygın, dilden bağımsız bir veri biçimidir. Daha fazla bilgi için json.org adresine bakın.