Başlarken

Bu belgede, Google Kitaplar API'sini kullanmak için gereken temel bilgiler ayrıntılı olarak açıklanmaktadır.

1. Giriş
2. Başlamadan önce
   1. Google Hesabı edinme
   2. Kitaplar'ı kullanma
   3. İstekleri yetkilendirme ve uygulamanızı tanımlama hakkında bilgi edinin.
3. Books API arka planı
   1. Kitaplarla ilgili 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 Kitaplar API ile etkileşim kurabilen uygulamalar yazmak isteyen geliştiriciler için hazırlanmıştır. Google Kitaplar, dünyanın kitaplarını dijitalleştirme vizyonuna sahiptir. Google Kitaplar API'sini kullanarak içerik arayabilir, kimliği doğrulanmış bir kullanıcının kişisel kitaplığını düzenleyebilir ve değiştirebilirsiniz.

Başlamadan önce

Google Hesabı edinme

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

Kitaplar'ı tanıma

Google Kitaplar kavramlarına aşina değilseniz kodlamaya başlamadan önce bu belgeyi okumanız ve kullanıcı arayüzünü denemeniz gerekir. Bu belgede, web programlama kavramları ve web veri biçimleri hakkında bilgi sahibi olduğunuz varsayılır.

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

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 Kitaplar API'sindeki "Kitaplığım" bölümündeki tüm işlemler özel olarak kabul edilir ve kimlik doğrulama ile yetkilendirme gerektirir. Ayrıca, Google Kitaplar verilerini değiştiren tüm işlemler yalnızca bu 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 bir tanımlayıcı (ör. API anahtarı) ile birlikte gönderilmesi gerekir.

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

Books API 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 ifade eder. Books API'deki birincil kaynaktır. Bu API'deki diğer tüm kaynaklar bir hacim içerir veya hacimle ilgili açıklama içerir.
• Kitaplık: Kitaplık, ciltlerden oluşan bir koleksiyondur. Google Kitaplar, her kullanıcı için önceden tanımlanmış bir dizi kitaplık sunar. Bunlardan bazıları tamamen kullanıcı tarafından yönetilir, bazıları kullanıcının etkinliğine göre otomatik olarak doldurulur, bazıları ise karışıktır. Kullanıcılar, her zaman manuel olarak doldurulan diğer kitaplıkları oluşturabilir, değiştirebilir veya silebilir. Kitaplıklar, kullanıcı tarafından gizli veya herkese açık hale getirilebilir.

  Not: Kitaplık oluşturma ve silme işlemlerinin yanı sıra kitaplıklardaki gizlilik ayarlarını değiştirme işlemleri şu anda yalnızca Google Kitaplar sitesi üzerinden yapılabilir.

• Yorum: Bir cildin yorumu, yıldız puanı ve/veya metin kombinasyonudur. Kullanıcılar, her cilt için bir yorum gönderebilir. Ayrıca, dış kaynaklardan alınan yorumlar da uygun şekilde ilişkilendirilerek gösterilir.
• Okuma Konumu: Okuma konumu, kullanıcının bir ciltte en son okuduğu yeri gösterir. Kullanıcılar, cilt başına yalnızca bir okuma konumuna sahip olabilir. Kullanıcı bu cildi daha önce açmadıysa okuma konumu mevcut değildir. Okuma konumu, kelime çözünürlüğüne kadar ayrıntılı konum bilgilerini saklayabilir. Bu bilgiler her zaman kullanıcının gizli bilgileridir.

Books API veri modeli

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

• Cilt kaynağı: Bir cildi temsil eder.
• Kitaplık kaynağı: Belirli bir kullanıcıya ait tek bir kitaplığı temsil eder.

Books API veri modeli, koleksiyon adı verilen kaynak gruplarına dayanır:

Volume Collection

Cilt koleksiyonu, Google Kitaplar tarafından yönetilen her bir cilt kaynağının koleksiyonudur. Bu nedenle, tüm birim kaynaklarını listelemezsiniz ancak bir grup arama terimine uyan tüm birimleri listeleyebilirsiniz.

Kitaplık koleksiyonu

Kitaplık koleksiyonu, Google Kitaplar tarafından yönetilen tüm kitaplık kaynaklarından oluşur. Kitaplıklar her zaman belirli bir kullanıcının kitaplığı bağlamında referans verilmelidir. Kitaplıklar sıfır veya daha fazla cilt içerebilir.

Google, her kullanıcı için önceden tanımlanmış bir dizi kitaplık sunar:

• Favoriler: Değiştirilebilir kitaplık.
• Satın alınanlar: Kullanıcının satın aldığı ciltlerle doldurulur. Kullanıcı, birimleri manuel olarak ekleyemez veya kaldıramaz.
• Okuma: Değişken kitap rafı.
• Şimdi Okuyun: Değiştirilebilir kitap rafı.
• Okundu: Değişken kitaplık.
• İncelendi: Kullanıcının incelediği ciltlerle doldurulur. Kullanıcı, birimleri manuel olarak ekleyemez veya kaldıramaz.
• Son Görüntülenenler: Kullanıcının web okuyucuda kısa süre önce açtığı ciltlerle doldurulur. Kullanıcı, birimleri manuel olarak ekleyemez.
• E-kitaplarım: Değişken kitaplık. Satın alınan kitaplar otomatik olarak eklenir ancak manuel olarak kaldırılabilir.
• Sizin İçin Kitaplar: Kişiselleştirilmiş kitap önerileriyle doldurulur. Kullanıcı için önerimiz yoksa bu kitaplık mevcut değildir.

Örnek kitaplıklar:

• "Favoriler"
• "Harry Potter"
• "E-kitaplarım"
• "Geçiş yap"
• "Twilight"
• "Ejderha Dövmeli Kız"

Books API işlemleri

Aşağıdaki tabloda açıklandığı gibi, Books API'deki koleksiyonlar ve kaynaklar üzerinde beş farklı yöntem çağırabilirsiniz.

İşlem	Açıklama	REST HTTP eşlemeleri
list	Bir koleksiyondaki belirtilen kaynak alt kümesini listeler.	GET koleksiyon URI'sinde.
insert	Bir koleksiyona yeni bir kaynak ekler (yeni bir kaynak oluşturur).	Yeni bir kaynağın verilerini ilettiğiniz bir koleksiyon URI'sinde POST.
get	Belirli bir kaynağı alır.	Kaynak URI'sinde GET.
update	Belirli bir kaynağı günceller.	Güncellenen kaynağın verilerini ilettiğiniz kaynak URI'sinde PUT.
sil	Belirli bir kaynağı siler.	Silinecek kaynağın verilerini ilettiğiniz kaynak URI'sinde DELETE.

Çeşitli kaynak türleri için desteklenen işlemler aşağıdaki tabloda özetlenmiştir. Kullanıcının özel verileri için geçerli olan işlemler "Kitaplığım" işlemleri olarak adlandırılır ve tüm bu işlemler için kimlik doğrulama gerekir.

Kaynak Türü	Desteklenen işlemler
	list	insert	get	update	delete
Ciltler	evet*		evet
Raflar	evet*	evet, AUTHENTICATED	evet*	evet, AUTHENTICATED	evet, AUTHENTICATED
Okuma Konumları		evet, AUTHENTICATED	evet, AUTHENTICATED	evet, AUTHENTICATED	evet, AUTHENTICATED

*Bu işlemlerin hem AUTHENTICATED hem de kimliği doğrulanmamış sürümleri kullanılabilir. Kimliği doğrulanmış istekler kullanıcının gizli "Kitaplığım" verileri üzerinde, kimliği doğrulanmamış 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ı kodu gerekmez)

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, HTTP fiili kullanarak (ör. POST, GET, PUT veya DELETE) bir işlem belirtir. Aşağıdaki biçimde yer alan küresel olarak benzersiz bir URI ile kaynak 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, Kitaplar API işlemleri bölümünde açıklandığı gibi doğrudan REST HTTP fiilleriyle eşlenir.

Books API URI'lerinin biçimi şu şekildedir:

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

Burada resourceID, bir birim veya kitaplık kaynağının tanımlayıcısıdır ve parameters, sorguya uygulanacak parametrelerdir. Ayrıntılı bilgi için Sorgu parametresi referansı başlıklı makaleyi inceleyin.

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

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'de mylibrary ile yapılan işlemlerin yalnızca şu anda kimliği doğrulanmış kullanıcının özel kitaplık verileri için geçerli olduğunu unutmayın. API'deki desteklenen her işlem için kullanılan URI'lerin tümü Books API Referansı belgesinde özetlenmiştir.

Kitaplar API'sinde bu işlemin nasıl çalıştığına dair birkaç örneği aşağıda bulabilirsiniz.

Kapitone ile ilgili arama yapın:

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

s1gVAAAAYAAJ birimi hakkında bilgi edinme:

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

JavaScript'ten REST

Kitaplar API'sini, callback sorgu parametresini ve geri çağırma işlevini kullanarak JavaScript'ten (JSON-P olarak da bilinir) REST ile çağırabilirsiniz. Bu sayede, sunucu tarafı kodu yazmadan Kitaplar verilerini gösteren zengin uygulamalar yazabilirsiniz.

Not: access_token parametresini kullanarak bir OAuth 2.0 jetonu ileterek kimliği doğrulanmış yöntemleri çağırabilirsiniz. JavaScript ile kullanılacak 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 istemci kimliği oluşturduğunuzdan ve jetonunuzu alırken bu OAuth 2.0 kimlik bilgilerini kullandığınızdan emin olun.

Aşağıdaki örnekte, "harry potter" ile ilgili arama sonuçlarını göstermek için 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), rastgele veri yapılarını basit metin biçiminde sunan, yaygın şekilde kullanılan ve dilden bağımsız bir veri biçimidir. Daha fazla bilgi için json.org adresine bakın.