Discovery API, Google API की एक सूची उपलब्ध कराता है. इससे हर एपीआई के लिए, मशीन के पढ़ने लायक "खोज से जुड़ा दस्तावेज़" मेटाडेटा को वापस पाया जा सकता है.
यह दस्तावेज़ उन डेवलपर के लिए है जो Google API के साथ इंटरैक्ट करने के लिए, क्लाइंट लाइब्रेरी, IDE प्लगिन, और अन्य टूल लिखना चाहते हैं.
डिस्कवरी सेवा का बैकग्राउंड
कॉन्सेप्ट
Google APIs Discovery Service, दो बुनियादी सिद्धांतों पर आधारित है:
- एपीआई डायरेक्ट्री: इसमें उन सभी एपीआई की सूची होती है जो एपीआई डिस्कवरी सेवा के साथ काम करते हैं. हर डायरेक्ट्री एंट्री में, काम करने वाले एपीआई के बारे में जानकारी दिखती है. इसमें एपीआई का नाम, कम शब्दों में ब्यौरा, और दस्तावेज़ का लिंक शामिल होता है. किसी एपीआई की कई डायरेक्ट्री एंट्री हो सकती हैं. हर एंट्री, एपीआई के उस वर्शन के लिए होती है जो काम करता है.
- डिस्कवरी दस्तावेज़: किसी एपीआई के बारे में मशीन के पढ़ने लायक जानकारी. डिस्कवरी दस्तावेज़ में, एपीआई के किसी वर्शन के लिए प्लैटफ़ॉर्म के बारे में जानकारी होती है. इस दस्तावेज़ में, RESTful एचटीटीपी कॉल के ज़रिए हर एपीआई के अलग-अलग तरीकों को ऐक्सेस करने के बारे में जानकारी दी गई है. डिस्कवरी दस्तावेज़ में, एपीआई से जुड़े डेटा और तरीकों के बारे में जानकारी होती है. साथ ही, इसमें उपलब्ध OAuth स्कोप के बारे में जानकारी होती है. इसके अलावा, स्कीमा, तरीकों, पैरामीटर, और उपलब्ध पैरामीटर वैल्यू के बारे में जानकारी होती है.
डेटा मॉडल
संसाधन, एक यूनीक आइडेंटिफ़ायर वाली अलग डेटा इकाई होती है. Google APIs Discovery Service, ऊपर दिए गए कॉन्सेप्ट के आधार पर दो तरह के संसाधनों पर काम करती है.
एपीआई डायरेक्ट्री की सूची: एपीआई की सूची
हर डायरेक्ट्री एंट्री में, एपीआई का नाम/वर्शन पेयर होता है. इसमें यह जानकारी शामिल होती है:
- पहचान और ब्यौरे की जानकारी: नाम, वर्शन, टाइटल, और ब्यौरा.
- दस्तावेज़ की जानकारी: आइकॉन और दस्तावेज़ का लिंक.
- स्टेटस की जानकारी. इसमें स्टेटस लेबल और यह जानकारी शामिल होती है कि यह एपीआई का पसंदीदा वर्शन है या नहीं.
- खोज से जुड़े दस्तावेज़ का लिंक. यह एपीआई के खोज से जुड़े दस्तावेज़ का यूआरआई है. इसे पूरे यूआरएल के तौर पर दिया जाता है. उदाहरण के लिए,
https://serviceusage.googleapis.com/$discovery/rest?version=v1.
डिस्कवरी दस्तावेज़ संसाधन: किसी एपीआई के बारे में मशीन के पढ़ने लायक जानकारी
एपीआई डायरेक्ट्री में दी गई जानकारी के अलावा, डिस्कवरी दस्तावेज़ में यह जानकारी भी शामिल होती है:
- स्कीमा, जो एपीआई रिसॉर्स स्कीमा की एक सूची है. इसमें उस डेटा के बारे में बताया जाता है जिसे हर एपीआई में ऐक्सेस किया जा सकता है. Google APIs Discovery Service के स्कीमा, JSON स्कीमा पर आधारित होते हैं.
- तरीके. इनमें एपीआई के तरीकों की सूची और हर तरीके के लिए उपलब्ध पैरामीटर शामिल हैं.
- OAuth के दायरे, जो इस एपीआई के लिए उपलब्ध OAuth के दायरों की सूची की पहचान करता है.
- इनलाइन दस्तावेज़, जिसमें स्कीमा, तरीकों, पैरामीटर, और उपलब्ध पैरामीटर वैल्यू के बारे में कम शब्दों में जानकारी दी गई है.
एक डायरेक्ट्री कलेक्शन, एक एपीआई डायरेक्ट्री संसाधन और हर उस एपीआई के लिए डिस्कवरी दस्तावेज़ संसाधनों का कॉन्सेप्ट कंटेनर होता है जिसका इस्तेमाल किया जा सकता है.
कार्रवाइयां
Google APIs Discovery Service में, कलेक्शन और संसाधनों पर दो अलग-अलग तरीकों का इस्तेमाल किया जा सकता है. इनके बारे में यहां दी गई टेबल में बताया गया है.
| कार्रवाई | ब्यौरा | REST एचटीटीपी मैपिंग |
|---|---|---|
| list | इसमें, साथ काम करने वाले सभी एपीआई की सूची होती है. | GET डायरेक्ट्री रिसॉर्स यूआरआई पर. |
कॉल करने का स्टाइल
REST
Google APIs Discovery Service के साथ काम करने वाली कार्रवाइयों को सीधे तौर पर REST एचटीटीपी GET वर्ब पर मैप किया जाता है. इसके बारे में कार्रवाइयां में बताया गया है.
Google APIs Discovery Service के यूआरआई का फ़ॉर्मैट यह है:
https://API/$discovery/rest?version=VERSION
यहां API, डिस्कवरी दस्तावेज़ रिसॉर्स का आइडेंटिफ़ायर है. साथ ही, VERSION, एपीआई के किसी वर्शन का आइडेंटिफ़ायर है.
यहां कुछ उदाहरण दिए गए हैं, जिनसे पता चलता है कि Google APIs Discovery Service में यह कैसे काम करता है.
Google APIs Discovery Service के साथ काम करने वाले सभी एपीआई की सूची बनाएं:
GET https://discovery.googleapis.com/discovery/v1/apis
इसे अभी APIs Explorer में आज़माएं!
Service Usage API के वर्शन 1 के लिए, Discovery document पाएं:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1