इस दस्तावेज़ में उस बैकग्राउंड की जानकारी के बारे में बताया गया है जिसकी ज़रूरत 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 में मुख्य संसाधन है. इस एपीआई के अन्य सभी रिसॉर्स में या तो वॉल्यूम शामिल है या उसकी व्याख्या की गई है.
- Bookshelf: किताबों की अलमारी, किताबों का एक संग्रह होती है. Google Books
हर उपयोगकर्ता के लिए, पहले से तय की गई किताबों की शेल्फ़ का एक सेट उपलब्ध कराता है.
इनमें से कुछ शेल्फ़ को उपयोगकर्ता पूरी तरह से मैनेज करता है. इनमें से कुछ शेल्फ़,
उपयोगकर्ता की गतिविधि के हिसाब से अपने-आप भर जाती हैं. इनमें से कुछ शेल्फ़ अलग-अलग होती हैं. उपयोगकर्ता अन्य किताबों की अलमारी बना सकते हैं,
उनमें बदलाव कर सकते हैं या उन्हें मिटा सकते हैं. इन किताबों में, वॉल्यूम को हमेशा मैन्युअल तरीके से
भरा जाता है. किताबों की अलमारी को उपयोगकर्ता, निजी या सार्वजनिक बना सकता है.
ध्यान दें: फ़िलहाल, किताबों की अलमारी बनाने और मिटाने के साथ-साथ, किताबों की निजता सेटिंग में बदलाव करने का काम सिर्फ़ Google Books साइट पर किया जा सकता है.
- समीक्षा: किसी वॉल्यूम की समीक्षा, स्टार रेटिंग और/या टेक्स्ट को मिलाकर बनाई जाती है. उपयोगकर्ता एक वॉल्यूम में एक समीक्षा सबमिट कर सकता है. समीक्षाएं बाहरी सोर्स से भी उपलब्ध कराई जाती हैं और उन्हें सही तरीके से एट्रिब्यूट किया जाता है.
- पढ़ने की जगह: पढ़ने की स्थिति, उपयोगकर्ता के लिए किसी वॉल्यूम में पिछली बार पढ़े जाने की स्थिति बताती है. एक उपयोगकर्ता के पास हर वॉल्यूम के लिए, पढ़ने की सिर्फ़ एक पोज़िशन हो सकती है. अगर उपयोगकर्ता ने पहले उस वॉल्यूम को नहीं खोला है, तो पढ़ने की स्थिति मौजूद नहीं होगी. पढ़ने की पोज़िशन की मदद से, पेज की पूरी जानकारी को शब्द के रिज़ॉल्यूशन तक सेव किया जा सकता है. यह जानकारी उपयोगकर्ता के लिए हमेशा निजी रहती है.
Books API का डेटा मॉडल
संसाधन, एक यूनीक आइडेंटिफ़ायर वाली व्यक्तिगत डेटा इकाई होता है. Books API, ऊपर बताए गए सिद्धांतों के आधार पर दो तरह के संसाधनों पर काम करता है:
- वॉल्यूम का संसाधन: वॉल्यूम के बारे में बताता है.
- बुकशेल्फ़ संसाधन: किसी खास उपयोगकर्ता के लिए एक बुकशेल्फ़ दिखाता है.
Books API का डेटा मॉडल, संसाधनों के ग्रुप पर आधारित होता है. इन्हें कलेक्शन कहा जाता है:
- वॉल्यूम कलेक्शन
- वॉल्यूम कलेक्शन, Google Books की ओर से मैनेज किए जाने वाले हर वॉल्यूम से जुड़े संसाधन का कलेक्शन है.
इसका मतलब है कि आप वॉल्यूम वाले सभी संसाधनों की सूची नहीं बना सकते. हालांकि, खोज के लिए इस्तेमाल किए गए शब्दों के सेट से मेल खाने वाले सभी वॉल्यूम की सूची बना सकते हैं.
- बुकशेल्फ़ का संग्रह
- बुकशेल्फ़ में ऐसे सभी बुकशेल्फ़ संसाधन शामिल होते हैं जिन्हें Google Books मैनेज करता है. बुकशेल्फ़ का संदर्भ हमेशा किसी खास उपयोगकर्ता की लाइब्रेरी के हिसाब से दिया जाना चाहिए. बुकशेल्फ़ में शून्य या उससे ज़्यादा वॉल्यूम हो सकते हैं.
- पसंदीदा: बदली जा सकने वाली किताबों की अलमारी.
- खरीदा गया: यह संख्या, उपयोगकर्ता की खरीदारी की संख्या से अपने-आप भर जाती है. उपयोगकर्ता मैन्युअल रूप से आवाज़ नहीं जोड़ सकता या हटा नहीं सकता.
- पढ़ने के लिए: बुकशेल्फ़.
- अभी पढ़ा जा रहा है: बदली जा सकने वाली किताबों की अलमारी.
- पढ़ें: म्यूटेबल बुकशेल्फ़.
- समीक्षा की गई: इसमें ज़्यादा से ज़्यादा उपयोगकर्ता की समीक्षा की गई जानकारी अपने-आप भर जाती है. उपयोगकर्ता मैन्युअल रूप से आवाज़ नहीं जोड़ सकता या हटा नहीं सकता.
- हाल ही में देखी गई: इसमें ऐसा कॉन्टेंट मौजूद होता है जिसे उपयोगकर्ता ने हाल ही में वेब रीडर में खोला है. उपयोगकर्ता मैन्युअल रूप से आवाज़ नहीं जोड़ सकता.
- मेरी ई-बुक: म्यूटेबल बुकशेल्फ़. खरीदी गई किताबें अपने-आप जुड़ जाती हैं. हालांकि, उन्हें मैन्युअल तरीके से हटाया जा सकता है.
- आपके लिए किताबें: इसमें आपके हिसाब से वॉल्यूम के सुझाव दिए जाते हैं. अगर हमारे पास उस उपयोगकर्ता के लिए कोई सुझाव नहीं है, तो यह किताबों की अलमारी मौजूद नहीं होगी.
- "पसंदीदा"
- "हैरी पॉटर"
- "मेरी ई-बुक"
- "स्विच करें"
- "ट्वायलाइट"
- "द गर्ल विद द ड्रैगन टैटू"
Google हर उपयोगकर्ता को पहले से तय की गई किताबों की अलमारी उपलब्ध कराता है:
किताबों की अलमारी का उदाहरण:
Books API की कार्रवाइयां
Books API में, कलेक्शन और संसाधनों के लिए पांच अलग-अलग तरीके अपनाए जा सकते हैं. इनके बारे में इस टेबल में बताया गया है.
| कार्रवाई | जानकारी | REST एचटीटीपी मैपिंग |
|---|---|---|
| list | किसी कलेक्शन में संसाधनों के खास सबसेट की सूची बनाता है. | संग्रह यूआरआई पर GET. |
| डालें | किसी कलेक्शन में नया संसाधन शामिल करना (नया संसाधन बनाना). | कलेक्शन यूआरआई पर POST, जहां आप नए संसाधन के लिए डेटा पास करते हैं. |
| पाएं | कोई खास संसाधन मिलता है. | रिसॉर्स यूआरआई पर GET. |
| अपडेट करें | किसी खास संसाधन को अपडेट करता है. | संसाधन यूआरआई पर PUT, जहां आप अपडेट किए गए संसाधन के लिए डेटा पास करते हैं. |
| मिटाएं | किसी खास संसाधन को मिटाता है. | रिसॉर्स यूआरआई पर DELETE, जहां संसाधन को मिटाने के लिए डेटा पास किया जाता है. |
अलग-अलग तरह के संसाधनों के लिए काम करने वाली कार्रवाइयों की खास जानकारी नीचे दी गई टेबल में दी गई है. उपयोगकर्ता के निजी डेटा पर लागू होने वाली कार्रवाइयों को "मेरी लाइब्रेरी" कार्रवाइयां कहा जाता है और इन सभी कार्रवाइयों के लिए पुष्टि ज़रूरी होती है.
संसाधन किस तरह का है |
इस्तेमाल की जा सकने वाली कार्रवाइयां |
||||
|---|---|---|---|---|---|
| सूची | डालें | पाएं | अपडेट | मिटाएं | |
| वॉल्यूम | हां* | हां | |||
| बुकशेल्फ़ | हां* | हां, पुष्टि की गई | हां* | हां, पुष्टि की गई | हां, पुष्टि की गई |
| पढ़ने की जगह | हां, पुष्टि की गई | हां, पुष्टि की गई | हां, पुष्टि की गई | हां, पुष्टि की गई | |
*इन कार्रवाइयों के पुष्टि किए गए और बिना पुष्टि वाले वर्शन, दोनों उपलब्ध हैं. जहां पुष्टि किए गए अनुरोध, उपयोगकर्ता के निजी "मेरी लाइब्रेरी" डेटा पर ऑपरेट किए जाते हैं. वहीं, बिना पुष्टि वाले अनुरोध सिर्फ़ सार्वजनिक डेटा पर काम करते हैं.
कॉल करने के तरीके
एपीआई शुरू करने के कई तरीके हैं:
- सीधे REST का इस्तेमाल करना
- JavaScript से REST का इस्तेमाल करना (सर्वर-साइड कोड की ज़रूरत नहीं है)
आराम
REST, सॉफ़्टवेयर आर्किटेक्चर की एक स्टाइल है. यह डेटा का अनुरोध करने और उसमें बदलाव करने के लिए, आसान और एक जैसा तरीका उपलब्ध कराती है.
REST शब्द "रिप्रज़ेंटेशनल स्टेट ट्रांसफ़र" का छोटा रूप है. Google API के संदर्भ में, यह Google के सेव किए गए डेटा को दिखाने और उसमें बदलाव करने के लिए एचटीटीपी क्रियाओं का इस्तेमाल करता है.
RESTful सिस्टम में, संसाधनों को डेटा स्टोर में सेव किया जाता है. वहीं, क्लाइंट एक अनुरोध भेजता है कि सर्वर किसी खास काम (जैसे, संसाधन बनाना, वापस पाना, अपडेट करना या मिटाना) करता है. इसके बाद, सर्वर कार्रवाई करता है और जवाब देता है. आम तौर पर, यह अनुरोध, बताए गए संसाधन के तौर पर किया जाता है.
Google के RESTful एपीआई में, क्लाइंट एचटीटीपी कार्रवाई के बारे में बताता है, जैसे कि POST, GET, PUT या DELETE. यह ऐसे संसाधन के बारे में बताता है जो नीचे दिए गए फ़ॉर्म के दुनिया भर में मौजूद यूनीक यूआरआई की मदद से बनाया जाता है:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
सभी एपीआई संसाधनों में, एचटीटीपी से ऐक्सेस किए जा सकने वाले यूनीक यूआरआई होते हैं. इसलिए, REST डेटा कैश करने की सुविधा को चालू करती है. साथ ही, उसे वेब के डिस्ट्रिब्यूटेड इन्फ़्रास्ट्रक्चर के साथ काम करने के लिए ऑप्टिमाइज़ किया जाता है.
आपको एचटीटीपी 1.1 स्टैंडर्ड वाले दस्तावेज़ में तरीका की परिभाषाएं लग सकती हैं. इनमें GET, POST, PUT, और DELETE के लिए खास जानकारी शामिल होती है.
Books API में REST
इस सुविधा के साथ काम करने वाली कार्रवाइयां, सीधे 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
आप callback क्वेरी पैरामीटर और कॉलबैक फ़ंक्शन का इस्तेमाल करके, JavaScript से REST का इस्तेमाल करके Books API को शुरू कर सकते हैं, जिसे JSON-P भी कहा जाता है. इससे आपको ऐसे रिच ऐप्लिकेशन लिखने की सुविधा मिलती है जो बिना सर्वर साइड कोड लिखे, किताबों का डेटा दिखाते हैं.
ध्यान दें: access_token पैरामीटर का इस्तेमाल करके, OAuth 2.0 टोकन पास करके, पुष्टि किए गए तरीकों को कॉल किया जा सकता है. JavaScript के साथ इस्तेमाल करने के लिए OAuth 2.0 टोकन पाने के लिए, क्लाइंट-साइड वेब ऐप्लिकेशन के लिए OAuth 2.0 में बताए गए निर्देशों का पालन करें. API कंसोल के "एपीआई ऐक्सेस" टैब में, पक्का करें कि वेब ऐप्लिकेशन के लिए Client-ID सेट अप किया गया हो और अपना टोकन पाने के दौरान उन 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 ऑब्जेक्ट नोटेशन), आम तौर पर भाषा पर आधारित डेटा फ़ॉर्मैट है. यह आर्बिट्रेरी डेटा स्ट्रक्चर को टेक्स्ट में आसान तरीके से दिखाता है. ज़्यादा जानकारी के लिए, json.org पर जाएं.