पुराने सिस्टम के साथ काम करने से जुड़े दिशा-निर्देश

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

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

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

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

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

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

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

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

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

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

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

एपीआई अनुरोध

ऐसा फ़ंक्शन जिसे बदलना नहीं है

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

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

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

  • एचटीटीपी अनुरोध वाले हेडर का सेट, जो हर तरह के एपीआई अनुरोध के लिए ज़रूरी है. इस दिशा-निर्देश का मतलब है कि 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>).)

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

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

    यह उदाहरण इस सबसे सही तरीके को दिखाता है:

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

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

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

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

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

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

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

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

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

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

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

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

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