पुराने सिस्टम के साथ काम करने की सुविधा के लिए दिशा-निर्देश

YouTube Data API के हर अनुरोध में, एपीआई के उस वर्शन के बारे में बताया जा सकता है जिसका इस्तेमाल YouTube को उस अनुरोध को मैनेज करने के लिए करना चाहिए. अगर किसी अनुरोध में एपीआई वर्शन की जानकारी नहीं दी गई है, तो YouTube उस अनुरोध को हैंडल करने के लिए, एपीआई के सबसे पुराने वर्शन का इस्तेमाल करेगा. फ़िलहाल, 1 सबसे पुराना वर्शन है. कृपया एपीआई के वर्शन नंबर की इन विशेषताओं पर ध्यान दें:

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

  • एपीआई वर्शन नंबर में बढ़ोतरी होने का मतलब है कि रिलीज़ में ऐसे बदलाव किए गए हैं जो एपीआई के पिछले वर्शन के साथ काम नहीं करते.

इस दस्तावेज़ में, किसी खास एपीआई वर्शन के अपडेट के लिए, पुराने सिस्टम के साथ काम करने से जुड़े दिशा-निर्देश बताए गए हैं. यह ऊपर दिए गए पहले आइटम के बारे में है. इन दिशा-निर्देशों का मकसद, एपीआई की इन सुविधाओं के बीच अंतर करना है:

  • दिशा-निर्देशों में एपीआई की उस सुविधा के बारे में बताया गया है जो एपीआई के अनुरोधों को मैनेज करने के लिए इस्तेमाल किए जाने वाले एपीआई वर्शन में बदलाव न करने पर भी बदल सकती है. आपका कोड, इन बदलावों को बिना किसी रुकावट के मैनेज कर लेगा. उदाहरण के लिए, अगर YouTube एपीआई के जवाबों में नए एक्सएमएल टैग जोड़ता है, तो आपके कोड को उन टैग को अनदेखा करना चाहिए.

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

इस दस्तावेज़ के बारे में जानकारी

इस दस्तावेज़ में ये सेक्शन शामिल हैं:

  • एपीआई अनुरोध सेक्शन में, एचटीटीपी अनुरोध हेडर, एपीआई अनुरोध पैरामीटर, एक्सएमएल एलिमेंट के नाम (जैसा कि वे एपीआई अनुरोधों में दिखते हैं), और गलत तरीके से बनाए गए एपीआई अनुरोधों से जुड़े, पुराने सिस्टम के साथ काम करने से जुड़े दिशा-निर्देश बताए गए हैं.

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

  • सबसे सही तरीके सेक्शन में, अपने क्लाइंट ऐप्लिकेशन के साथ YouTube API को इंटिग्रेट करने के सुझाव दिए गए हैं.

एपीआई अनुरोध

ऐसी सुविधाएं जिन्हें बदलने का मकसद नहीं है

  • मौजूदा अनुरोध पैरामीटर.

  • उन पैरामीटर की मौजूदा पैरामीटर वैल्यू जिनकी वैल्यू एनोटेट की गई हैं या उन पैरामीटर वैल्यू का मतलब.

  • एपीआई पोस्ट (शामिल करें) या पुट (अपडेट करें) अनुरोधों में इस्तेमाल किए गए एक्सएमएल एलिमेंट के नाम.

  • एचटीटीपी अनुरोध हेडर का सेट, जो हर तरह के एपीआई अनुरोध के लिए ज़रूरी होता है. इस दिशा-निर्देश का मतलब है कि YouTube, ज़रूरी एचटीटीपी अनुरोध हेडर नहीं जोड़ेगा या मौजूदा वैकल्पिक अनुरोध हेडर को ज़रूरी नहीं बनाएगा.

  • एपीआई अनुरोध में, काम न करने वाले पैरामीटर को तब तक अनदेखा करने का तरीका, जब तक अनुरोध में strict पैरामीटर का इस्तेमाल न किया गया हो. यह पैरामीटर, YouTube को ऐसे एपीआई अनुरोध को अस्वीकार करने का निर्देश देता है जिसमें अमान्य अनुरोध पैरामीटर शामिल हों.

ऐसी सुविधाएं जिनमें बदलाव हो सकता है

  • YouTube, अनुरोध के लिए वैकल्पिक पैरामीटर जोड़ सकता है.

  • YouTube, उन मौजूदा पैरामीटर के लिए नई वैल्यू जोड़ सकता है जिनमें वैल्यू के सेट शामिल हैं.

  • YouTube ऐसे किसी भी अनुरोध को अस्वीकार कर सकता है जिसमें मान्य पैरामीटर में अमान्य पैरामीटर वैल्यू शामिल हों. इस वजह से, गलत तरीके से बनाए गए ऐसे अनुरोधों को अस्वीकार किया जा सकता है जिन्हें पार्स करने के लिए ज़रूरी शर्तों को कम करने की वजह से स्वीकार कर लिया गया था. ऐसा तब होगा, जब पार्स करने के लॉजिक को ठीक कर दिया जाएगा.

  • YouTube, वैकल्पिक एचटीटीपी अनुरोध हेडर जोड़ सकता है.

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

  • YouTube, ब्राउज़ की जा सकने वाली कैटगरी या उन कैटगरी के सेट में बदलाव कर सकता है जिन्हें नए अपलोड किए गए वीडियो को असाइन किया जा सकता है.

  • दस्तावेज़ में शामिल नहीं की गई सुविधाओं को किसी भी समय हटाया या बदला जा सकता है.

एपीआई से मिले रिस्पॉन्स

ऐसी सुविधाएं जिन्हें बदलने का मकसद नहीं है

  • मौजूदा एक्सएमएल टैग के नाम.

  • मीडिया आरएसएस स्पेसिफ़िकेशन का पालन करके, उस स्पेसिफ़िकेशन में बताए गए एलिमेंट का क्रम तय करना. ये एलिमेंट, फ़ीड एंट्री में कई बार दिखते हैं. उदाहरण के लिए, अगर किसी एंट्री में कई <media:thumbnail> टैग हैं, तो उन्हें अहमियत के हिसाब से क्रम में लगाया जाता है.

  • <category> टैग की term एट्रिब्यूट वैल्यू, जो किसी फ़ीड या फ़ीड एंट्री में बताए गए आइटम के टाइप की पहचान करती है. <feed> या <entry> टैग में, <id> टैग उस यूनीक रिसॉर्स की जानकारी देता है जिसकी पहचान एंट्री से की गई है. साथ ही, <category> टैग उस रिसॉर्स के टाइप की जानकारी देता है जिसकी जानकारी एंट्री में दी गई है. इस <category> टैग के लिए, स्कीम एट्रिब्यूट की वैल्यू http://schemas.google.com/g/2005#kind है. साथ ही, शब्द एट्रिब्यूट की वैल्यू से पता चलता है कि फ़ीड की एंट्री में वीडियो, प्लेलिस्ट के लिंक, सदस्यताएं, संपर्क या किसी अन्य इकाई का ब्यौरा दिया गया है या नहीं.

ऐसी सुविधाएं जो बदल सकती हैं

  • YouTube, एपीआई के जवाबों में नए एक्सएमएल टैग जोड़ सकता है.

  • YouTube, मौजूदा एक्सएमएल टैग में नए एट्रिब्यूट जोड़ सकता है.

  • मौजूदा एपीआई टैग को अलग-अलग वैल्यू के साथ दोहराया जा सकता है. उदाहरण के लिए, YouTube किसी अलग type वैल्यू वाला नया <media:restriction> टैग या किसी अलग scheme और role वैल्यू वाला नया <media:credit> टैग जोड़ सकता है.

  • एपीआई के जवाब में, एक्सएमएल टैग और एट्रिब्यूट का क्रम बदल सकता है.

  • एपीआई के रिस्पॉन्स से, वैकल्पिक चाइल्ड टैग हटाए जा सकते हैं.

  • दस्तावेज़ में शामिल नहीं की गई सुविधाओं को किसी भी समय हटाया या बदला जा सकता है.

सबसे सही तरीके

  • किसी एंट्री की पहचान करने के लिए, <id> टैग की वैल्यू का इस्तेमाल करें.

  • कोई एंट्री वापस पाने के लिए, self लिंक का इस्तेमाल करें.

  • किसी एंट्री में बदलाव करने या उसे अपडेट करने के लिए, edit लिंक का इस्तेमाल करें.

  • किसी वीडियो एंट्री के लिए <yt:videoid> टैग की वैल्यू का इस्तेमाल करके, वह वैल्यू पाएं जिसका इस्तेमाल YouTube उस वीडियो की खास ढंग से पहचान करने के लिए करता है. किसी लिंक से वीडियो आईडी को पार्स न करें.

  • एक फ़ीड से दूसरे फ़ीड पर जाने के लिए, <link>, <content>, और <gd:feedLink> टैग में पहचाने गए यूआरएल का इस्तेमाल करें. YouTube, यूआरएल के कुछ खास सेट के साथ काम करता है. इनसे, खास फ़ीड को भरोसेमंद तरीके से वापस पाया जा सकता है. यहां दिए गए फ़ीड यूआरएल के अलावा, आपको अपने फ़ीड के यूआरएल नहीं बनाने चाहिए. ऐसा इसलिए, क्योंकि ये अचानक काम करना बंद कर सकते हैं.

    • /feeds/api/videos/<videoid>
    • /feeds/api/users/default
    • /feeds/api/users/default/uploads
    • /feeds/api/users/default/favorites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/playlists
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (ज़्यादा जानकारी के लिए, रेफ़रंस गाइड देखें)

  • एपीआई के जवाब में, यूआरएल से अंकों या अक्षरों से बनी पहचानों को पार्स न करें. एपीआई के जवाबों में, YouTube की वेबसाइट पर मौजूद संसाधनों से लिंक किए गए आइडेंटिफ़ायर के लिए खास टैग शामिल होते हैं. जैसे, वीडियो आईडी (<yt:videoid>) और उपयोगकर्ता नाम (<name> और <media:credit>).

  • अगर जानकारी डालने (POST) या अपडेट करने (PUT) के लिए एपीआई अनुरोध सबमिट किया जाता है, तो उस अनुरोध के एक्सएमएल रिस्पॉन्स का इस्तेमाल करके यह पता लगाएं कि अनुरोध में कौनसी टैग वैल्यू, YouTube ने असल में सेव की थीं. एपीआई अनुरोधों के लिए, पुराने सिस्टम के साथ काम करने के दिशा-निर्देशों में बताया गया है कि YouTube किसी संसाधन को डालने या अपडेट करने के दौरान, सेव की गई जानकारी में बदलाव कर सकता है. इसका मतलब है कि अनुरोध में मौजूद कुछ टैग को अनदेखा किया जा सकता है.

  • एक्सएमएल फ़ीड को वापस लाने पर, फ़ीड की एंट्री से जुड़े ऐसे एक्सएमएल टैग और एट्रिब्यूट सेव करें जिन्हें आपके ऐप्लिकेशन में पहचाना नहीं गया है. ऐसा तब करें, जब आपका ऐप्लिकेशन उपयोगकर्ता को उस एंट्री को अपडेट करने की अनुमति देता हो. अगर उपयोगकर्ता संसाधन को अपडेट करता है, तो आपके ऐप्लिकेशन को अपडेट के अनुरोध में, ऐसे सभी टैग और एट्रिब्यूट शामिल करने चाहिए जिन्हें पहचाना नहीं जा सका. ऐसा करने से यह पक्का होता है कि आपका ऐप्लिकेशन, किसी संसाधन को अपडेट करने की प्रोसेस में, एपीआई की नई सुविधाओं से जुड़ी जानकारी को गलती से न मिटा दे.

    इस सबसे सही तरीके के बारे में यहां दिए गए उदाहरण में बताया गया है:

    1. आपका ऐप्लिकेशन, उपयोगकर्ता को वीडियो का ब्यौरा अपडेट करने की सुविधा देता है.
    2. आपका ऐप्लिकेशन, एपीआई का इस्तेमाल करके वीडियो एंट्री को वापस लाता है, लेकिन एंट्री में मौजूद किसी टैग को नहीं पहचानता.
    3. उपयोगकर्ता, वीडियो के ब्यौरे में बदलाव करता है.
    4. आपके ऐप्लिकेशन को एपीआई को पूरी वीडियो एंट्री वापस भेजनी होगी. एंट्री में, दूसरे चरण में शामिल वह टैग शामिल होना चाहिए जिसे पहचाना नहीं जा सका. ऐसा न करने पर, उस वैल्यू को मिटाया जा सकता है.

  • टैग की वैल्यू दिखाने की कोशिश करने से पहले, पक्का करें कि टैग मौजूद हो और उसमें कोई वैल्यू हो.

  • जैसा कि ऊपर बताया गया है, YouTube उन मौजूदा टैग या एट्रिब्यूट के लिए नई वैल्यू जोड़ सकता है जिनमें वैल्यू के सेट शामिल हैं. आम तौर पर, आपका कोड उन एक्सएमएल एलिमेंट की वैल्यू को पार्स करना चाहिए जिनमें वैल्यू के सेट शामिल हैं. इसके बाद, उन वैल्यू के हिसाब से कार्रवाइयां तय करनी चाहिए. हमारा सुझाव है कि एलिमेंट के लिए सिर्फ़ एक वैल्यू दी गई हो, तब भी ऐसा करें.

    उदाहरण के लिए, <media:credit> टैग किसी वीडियो के मालिक की पहचान करता है. टैग के role एट्रिब्यूट की दस्तावेज़ में दी गई वैल्यू सिर्फ़ uploader है. इससे पता चलता है कि वीडियो को YouTube पार्टनर ने अपलोड किया है. इस सबसे सही तरीके के मुताबिक, आपके ऐप्लिकेशन को यह पुष्टि करनी चाहिए कि टैग के role एट्रिब्यूट की वैल्यू वाकई uploader है. इसके बाद ही, उस उपयोगकर्ता को वीडियो के मालिक के तौर पर पहचाना जाना चाहिए. (इससे यह पक्का होता है कि अगर YouTube किसी वीडियो के लिए डायरेक्टर जैसे दूसरे क्रेडिट जोड़ता है, तो आपका कोड वीडियो के मालिक की गलत पहचान न करे.)

    • अगर किसी टैग में वैल्यू का एनोटेट किया गया सेट है और आपको उस टैग की वैल्यू नहीं पता है, तो आपको उस पूरे <entry> को अनदेखा करना चाहिए जिसमें वह टैग दिखता है.

    • अगर आपको <category> टैग के लिए term एट्रिब्यूट की वैल्यू समझ नहीं आ रही है, तो उस सदस्यता फ़ीड की एंट्री को अनदेखा करें. इस टैग की scheme एट्रिब्यूट की वैल्यू http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat है. वह टैग, उस सदस्यता के टाइप की पहचान करता है जिसकी पहचान एंट्री से की गई है. अगर आपका ऐप्लिकेशन सदस्यता के टाइप की पहचान नहीं करता है, तो उसे उस एंट्री की जानकारी नहीं दिखानी चाहिए.

    • अगर किसी दूसरे एट्रिब्यूट की वैल्यू का सेट एनोटेट किया गया है और आपको उस एट्रिब्यूट की वैल्यू नहीं पता है, तो आपको उस टैग को अनदेखा करना चाहिए जिसमें एट्रिब्यूट दिखता है.

  • आपके ऐप्लिकेशन कोड को किसी भी समय yt:error मैसेज मिल सकता है. अगर एपीआई का कोई काम पूरा नहीं होता है, तो आपके ऐप्लिकेशन को गड़बड़ी की पहचान करनी चाहिए और उपयोगकर्ता को काम का मैसेज दिखाना चाहिए.

  • YouTube, वीडियो की कैटगरी तय करने के लिए कभी भी नई कैटगरी जोड़ सकता है. YouTube, मौजूदा कैटगरी को अपडेट या बंद भी कर सकता है. http://gdata.youtube.com/schemas/2007/categories.cat से, मौजूदा कैटगरी फ़ाइल को वापस पाया जा सकता है.

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

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

    • अगर आपके ऐप्लिकेशन में उपयोगकर्ताओं को वीडियो अपलोड करने की सुविधा है, तो वीडियो अपलोड करने से पहले, कैटगरी की अपडेट की गई फ़ाइल भी वापस पाएं. साथ ही, पुष्टि करें कि अपलोड किए गए वीडियो से जुड़ी कैटगरी अब भी असाइन की जा सकती है. ज़्यादा जानकारी के लिए, रेफ़रंस गाइड देखें. (ध्यान दें कि अगर किसी ऐसे वीडियो को असाइन करने की कोशिश की जाती है जिसे असाइन नहीं किया जा सकता, तो एपीआई गड़बड़ी का मैसेज दिखाएगा. इसके लिए, <code> टैग की वैल्यू deprecated होगी.)

  • किसी फ़ीड में एंट्री के पिछले और/या अगले पेज के पेजेशन लिंक की पहचान करने के लिए, एपीआई रिस्पॉन्स में <link> टैग का इस्तेमाल करें. ज़्यादा जानकारी के लिए, रेफ़रंस गाइड का नतीजों को पेज करके देखना सेक्शन देखें.