आरंभ करना

इस दस्तावेज़ में, Google Books API का इस्तेमाल करने के लिए ज़रूरी बुनियादी जानकारी दी गई है.

परिचय

यह दस्तावेज़ उन डेवलपर के लिए है जो ऐसे ऐप्लिकेशन बनाना चाहते हैं जो Google Books API के साथ इंटरैक्ट कर सकें. Google Books का मकसद, दुनिया भर की किताबों को डिजिटल बनाना है. Google Books API का इस्तेमाल करके, ये काम किए जा सकते हैं: कॉन्टेंट खोजना, पुष्टि किए गए उपयोगकर्ता की निजी लाइब्रेरी को व्यवस्थित करना, और उसमें बदलाव करना.

शुरू करने से पहले

Google खाता पाना

जांच के लिए, आपके पास Google खाता होना चाहिए. अगर आपके पास पहले से ही कोई टेस्ट खाता है, तो आपको कुछ और करने की ज़रूरत नहीं है. Google Books के यूज़र इंटरफ़ेस (यूआई) पर जाकर, टेस्ट डेटा को सेट अप, उसमें बदलाव या उसे देखा जा सकता है.

Books के बारे में जानकारी

अगर आपको Google Books के कॉन्सेप्ट के बारे में जानकारी नहीं है, तो कोडिंग शुरू करने से पहले, आपको यह दस्तावेज़ पढ़ना चाहिए. साथ ही, यूज़र इंटरफ़ेस को आज़माना चाहिए. इस दस्तावेज़ में यह माना गया है कि आपको वेब प्रोग्रामिंग के कॉन्सेप्ट और वेब डेटा फ़ॉर्मैट के बारे में जानकारी है.

अनुरोधों को अनुमति देने और अपने ऐप्लिकेशन की पहचान बताने के बारे में जानकारी

जब आपका ऐप्लिकेशन निजी डेटा को ऐक्सेस करने का अनुरोध करता है, तब इस अनुरोध की अनुमति किसी ऐसे उपयोगकर्ता को देनी चाहिए जिसके पास डेटा का ऐक्सेस हो.

खास तौर पर, Google Books API में "मेरी लाइब्रेरी" के तहत की जाने वाली सभी कार्रवाइयों को निजी माना जाता है. इसके लिए, पुष्टि करने और अनुमति देने की ज़रूरत होती है. इसके अलावा, Google Books के डेटा में बदलाव करने वाली कोई भी कार्रवाई सिर्फ़ उस उपयोगकर्ता के ज़रिए की जा सकती है जिसके पास उस डेटा का मालिकाना हक है.

जब आपका ऐप्लिकेशन सार्वजनिक डेटा को ऐक्सेस करने का अनुरोध करता है, तब इस अनुरोध की अनुमति लेने की ज़रूरत नहीं होती. हालांकि, इसके साथ एक आइडेंटिफ़ायर होना ज़रूरी है, जैसे कि एपीआई पासकोड.

अनुरोधों को अनुमति देने और एपीआई कुंजियों का इस्तेमाल करने के तरीके के बारे में जानने के लिए, 'एपीआई का इस्तेमाल करना' दस्तावेज़ में अनुरोधों को अनुमति देना और अपने ऐप्लिकेशन की पहचान बताना लेख पढ़ें.

Books API के बारे में जानकारी

किताबों से जुड़े कॉन्सेप्ट

Google Books को चार बुनियादी सिद्धांतों के आधार पर बनाया गया है:

• वॉल्यूम: वॉल्यूम, Google Books पर होस्ट किए गए उस डेटा को दिखाता है जो किसी किताब या पत्रिका के बारे में होता है. यह Books API में मुख्य संसाधन है. इस एपीआई में मौजूद अन्य सभी संसाधनों में, वॉल्यूम की जानकारी शामिल होती है या उन्हें एनोटेट किया जाता है.
• किताबों की अलमारी: किताबों की अलमारी, वॉल्यूम का एक कलेक्शन होती है. Google Books, हर उपयोगकर्ता के लिए पहले से तय की गई कुछ बुकशेल्फ़ उपलब्ध कराता है. इनमें से कुछ को उपयोगकर्ता पूरी तरह से मैनेज करता है, कुछ को उपयोगकर्ता की गतिविधि के आधार पर अपने-आप भरा जाता है, और कुछ को दोनों तरह से मैनेज किया जाता है. उपयोगकर्ता, किताबों की अन्य अलमारियां बना सकते हैं, उनमें बदलाव कर सकते हैं या उन्हें मिटा सकते हैं. इन अलमारियों में हमेशा मैन्युअल तरीके से वॉल्यूम भरे जाते हैं. उपयोगकर्ता, बुकशेल्फ़ को निजी या सार्वजनिक के तौर पर सेट कर सकता है.

  ध्यान दें: फ़िलहाल, किताबों की शेल्फ़ बनाना, उन्हें मिटाना, और उन पर निजता सेटिंग में बदलाव करना सिर्फ़ Google Books की साइट पर किया जा सकता है.

• समीक्षा: किसी वॉल्यूम की समीक्षा में स्टार रेटिंग और/या टेक्स्ट शामिल होता है. कोई उपयोगकर्ता, हर वॉल्यूम के लिए एक समीक्षा सबमिट कर सकता है. बाहरी स्रोतों से भी समीक्षाएं उपलब्ध कराई जाती हैं और उन्हें सही तरीके से एट्रिब्यूट किया जाता है.
• पढ़ने की स्थिति: पढ़ने की स्थिति से पता चलता है कि किसी उपयोगकर्ता ने किसी वॉल्यूम को आखिरी बार कहां तक पढ़ा था. किसी व्यक्ति के पास हर वॉल्यूम के लिए, पढ़ने की सिर्फ़ एक पोज़िशन हो सकती है. अगर उपयोगकर्ता ने उस वॉल्यूम को पहले नहीं खोला है, तो पढ़ने की स्थिति मौजूद नहीं होती. पढ़ने की स्थिति से, किसी शब्द के रिज़ॉल्यूशन तक की जानकारी सेव की जा सकती है. यह जानकारी हमेशा उपयोगकर्ता के लिए निजी होती है.

Books API का डेटा मॉडल

संसाधन, एक यूनीक आइडेंटिफ़ायर वाली अलग-अलग डेटा इकाई होती है. Books API, ऊपर बताए गए कॉन्सेप्ट के आधार पर दो तरह के संसाधनों पर काम करता है:

• वॉल्यूम रिसोर्स: यह किसी वॉल्यूम को दिखाता है.
• पुस्तकों की शेल्फ़ का संसाधन: यह किसी उपयोगकर्ता के लिए एक शेल्फ़ को दिखाता है.

Books API का डेटा मॉडल, संसाधनों के ग्रुप पर आधारित होता है. इन्हें कलेक्शन कहा जाता है:

वॉल्यूम कलेक्शन

वॉल्यूम कलेक्शन, Google Books की ओर से मैनेज किए जाने वाले हर वॉल्यूम रिसॉर्स का कलेक्शन होता है. इसलिए, सभी वॉल्यूम संसाधनों को सूचीबद्ध नहीं किया जा सकता. हालांकि, खोज के लिए इस्तेमाल हुए शब्दों के सेट से मेल खाने वाले सभी वॉल्यूम को सूचीबद्ध किया जा सकता है.

किताबों की अलमारी वाला कलेक्शन

किताबों की अलमारी के कलेक्शन में, Google Books से मैनेज किए जाने वाले सभी किताबों की अलमारी के संसाधन शामिल होते हैं. पुस्तकों की अलमारियों का रेफ़रंस हमेशा किसी उपयोगकर्ता की लाइब्रेरी के हिसाब से दिया जाना चाहिए. पुस्तकों की अलमारियों में, शून्य या उससे ज़्यादा वॉल्यूम हो सकते हैं.

Google, हर उपयोगकर्ता के लिए पहले से तय की गई कुछ बुकशेल्फ़ उपलब्ध कराता है:

• पसंदीदा: इसमें बदलाव किया जा सकता है.
• खरीदा गया: इसमें उपयोगकर्ता की ओर से खरीदे गए वॉल्यूम की जानकारी होती है. उपयोगकर्ता, वॉल्यूम को मैन्युअल तरीके से जोड़ या हटा नहीं सकता.
• पढ़ने के लिए: बदलाव की जा सकने वाली किताबों की अलमारी.
• अभी पढ़ी जा रही है: बदलाव की जा सकने वाली किताबों की अलमारी.
• पढ़ ली गई: इसमें बदलाव किया जा सकता है.
• समीक्षा की गई: इसमें वे वॉल्यूम शामिल होते हैं जिनकी समीक्षा उपयोगकर्ता ने की है. उपयोगकर्ता, वॉल्यूम को मैन्युअल तरीके से जोड़ या हटा नहीं सकता.
• हाल ही में देखी गई: इसमें वे किताबें शामिल होती हैं जिन्हें उपयोगकर्ता ने हाल ही में वेब रीडर में खोला है. उपयोगकर्ता, वॉल्यूम को मैन्युअल तरीके से नहीं जोड़ सकता.
• मेरी ई-बुक: किताबों की अलमारी में बदलाव किया जा सकता है. खरीदी गई किताबें अपने-आप जुड़ जाती हैं, लेकिन उन्हें मैन्युअल तरीके से हटाया जा सकता है.
• आपके लिए किताबें: इसमें आपकी पसंद के हिसाब से वॉल्यूम के सुझाव दिए जाते हैं. अगर हमारे पास उपयोगकर्ता के लिए कोई सुझाव नहीं है, तो यह बुकशेल्फ़ नहीं दिखेगी.

शेल्फ़ के उदाहरण:

• "पसंदीदा"
• "हैरी पॉटर"
• "मेरी ई-बुक"
• "स्विच करें"
• "ट्वाइलाइट"
• "द गर्ल विद द ड्रैगन टैटू"

Books API के ऑपरेशन

Books API में, कलेक्शन और संसाधनों के लिए पांच अलग-अलग तरीकों का इस्तेमाल किया जा सकता है. इनके बारे में यहां दी गई टेबल में बताया गया है.

अलग-अलग तरह के संसाधनों के लिए उपलब्ध कार्रवाइयों की जानकारी, यहां दी गई टेबल में दी गई है. किसी व्यक्ति के निजी डेटा पर लागू होने वाली कार्रवाइयों को "मेरी लाइब्रेरी" कार्रवाइयां कहा जाता है. इन सभी कार्रवाइयों के लिए, पुष्टि करना ज़रूरी है.

*इन कार्रवाइयों के लिए, AUTHENTICATED और बिना पुष्टि किए गए, दोनों वर्शन उपलब्ध हैं. पुष्टि किए गए अनुरोध, उपयोगकर्ता के निजी "मेरी लाइब्रेरी" डेटा पर काम करते हैं. वहीं, बिना पुष्टि किए गए अनुरोध सिर्फ़ सार्वजनिक डेटा पर काम करते हैं.

कॉल करने के स्टाइल

एपीआई को कई तरीकों से इस्तेमाल किया जा सकता है:

• REST का सीधे तौर पर इस्तेमाल करना
• JavaScript से REST का इस्तेमाल करना (सर्वर-साइड कोड की ज़रूरत नहीं है)

REST

REST, सॉफ़्टवेयर आर्किटेक्चर का एक स्टाइल है. यह डेटा में बदलाव करने और डेटा का अनुरोध करने का आसान और एक जैसा तरीका उपलब्ध कराता है.

"Representational State Transfer" को कम शब्दों में REST कहते हैं. Google APIs के संदर्भ में, इसका मतलब Google के पास सेव किए गए डेटा को वापस पाने और उसमें बदलाव करने के लिए, एचटीटीपी वर्ब का इस्तेमाल करना है.

RESTful सिस्टम में, रिसॉर्स को डेटा स्टोर में सेव किया जाता है. क्लाइंट, सर्वर को ऐसा अनुरोध भेजता है कि वह कोई खास कार्रवाई करे. जैसे, किसी रिसॉर्स बनाना, वापस पाना, अपडेट करना या मिटाना. इसके बाद, सर्वर कार्रवाई करता है और जवाब भेजता है. यह जवाब अक्सर, बताए गए रिसॉर्स के तौर पर होता है.

Google के RESTful API में, क्लाइंट किसी कार्रवाई के लिए एचटीटीपी वर्ब का इस्तेमाल करता है. जैसे, POST, GET, PUT या DELETE. यह इस फ़ॉर्म में मौजूद, दुनिया भर में पहचाने जाने वाले यूआरआई के ज़रिए किसी रिसॉर्स के बारे में बताता है:

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

सभी एपीआई संसाधनों के पास एचटीटीपी से ऐक्सेस किए जा सकने वाले यूआरआई होते हैं. इसलिए, REST से डेटा को कैश मेमोरी में सेव किया जा सकता है. साथ ही, इसे वेब के डिस्ट्रिब्यूटेड इंफ़्रास्ट्रक्चर के साथ काम करने के लिए ऑप्टिमाइज़ किया जाता है.

आपको एचटीटीपी 1.1 के स्टैंडर्ड के दस्तावेज़ में, मेथड की परिभाषाएं मिल सकती हैं. इनमें GET, POST, PUT, और DELETE के लिए खास जानकारी शामिल है.

Books API में REST

Books API के साथ काम करने वाले ऑपरेशन, सीधे तौर पर REST एचटीटीपी वर्ब से मैप होते हैं. इनके बारे में Books API के ऑपरेशन में बताया गया है.

Books API के यूआरआई के लिए ये फ़ॉर्मैट इस्तेमाल किए जाते हैं:

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

यहां resourceID, किसी वॉल्यूम या बुकशेल्फ़ संसाधन का आइडेंटिफ़ायर है. साथ ही, parameters, क्वेरी पर लागू होने वाले कोई भी पैरामीटर हैं. ज़्यादा जानकारी के लिए, क्वेरी पैरामीटर की जानकारी देखें.

resourceID पाथ एक्सटेंशन के फ़ॉर्मैट से, यह पता चलता है कि फ़िलहाल किस संसाधन पर काम किया जा रहा है. उदाहरण के लिए:

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

ध्यान दें कि यूआरआई में mylibrary वाले ऑपरेशन, सिर्फ़ फ़िलहाल पुष्टि किए गए उपयोगकर्ता की निजी लाइब्रेरी के डेटा पर लागू होते हैं. एपीआई में काम करने वाली हर कार्रवाई के लिए इस्तेमाल किए गए यूआरआई के पूरे सेट की खास जानकारी, Books API के रेफ़रंस वाले दस्तावेज़ में दी गई है.

यहां Books API में इसके काम करने के तरीके के कुछ उदाहरण दिए गए हैं.

क्विल्टिंग के बारे में खोजें:

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

वॉल्यूम s1gVAAAAYAAJ के बारे में जानकारी पाएं:

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

JavaScript से REST

JavaScript (इसे JSON-P भी कहा जाता है) से REST का इस्तेमाल करके, Books API को शुरू किया जा सकता है. इसके लिए, callback क्वेरी पैरामीटर और कॉलबैक फ़ंक्शन का इस्तेमाल करें. इससे आपको ऐसे ऐप्लिकेशन लिखने की सुविधा मिलती है जो सर्वर साइड कोड लिखे बिना, Books का डेटा दिखाते हैं.

ध्यान दें: access_token पैरामीटर का इस्तेमाल करके, OAuth 2.0 टोकन पास करके पुष्टि किए गए तरीकों को कॉल किया जा सकता है. JavaScript के साथ इस्तेमाल करने के लिए OAuth 2.0 टोकन पाने के लिए, क्लाइंट-साइड वेब ऐप्लिकेशन के लिए OAuth 2.0 में दिए गए निर्देशों का पालन करें. APIs Console के "एपीआई ऐक्सेस" टैब में जाकर, पक्का करें कि आपने वेब ऐप्लिकेशन के लिए क्लाइंट आईडी सेट अप किया हो. साथ ही, टोकन पाने के लिए OAuth 2.0 क्रेडेंशियल का इस्तेमाल किया हो.

यहां दिए गए उदाहरण में, "हैरी पॉटर" के लिए खोज के नतीजे दिखाने के लिए, इस तरीके का इस्तेमाल किया गया है:

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

डेटा फ़ॉर्मैट

JSON

JSON (JavaScript Object Notation) एक सामान्य डेटा फ़ॉर्मैट है. यह किसी भी भाषा पर निर्भर नहीं करता. यह किसी भी डेटा स्ट्रक्चर को टेक्स्ट के तौर पर दिखाता है. ज़्यादा जानकारी के लिए, json.org पर जाएं.