अनुरोध सर्वर तक पहुँच सकता है, भले ही आपके ऐप्लिकेशन को कभी प्रतिक्रिया न मिले। इसलिए संदेश भेजने के लिए फिर से प्रयास शुरू करने से पहले आपके इंटीग्रेशन में इस अनिश्चितता से निपटने की नीति होनी चाहिए।
Bird के REST SDK, TypeScript, Python, Go और PHP के लिए यही अनुरोध प्रबंधन देते हैं। Swift और Kotlin पैकेज REST API के बजाय Realtime सब्सक्रिप्शन के लिए हैं।
Bird SDK क्या संभालता है?
SDK अनुरोध के दोहराए जाने वाले काम संभालता है, जिनमें फिर से प्रयास, रूटिंग और डुप्लिकेट से सुरक्षा शामिल हैं।
डेटा बदलने वाले ऑपरेशन के लिए यह एक Idempotency-Key बनाता है और आंतरिक फिर से प्रयासों में उसे वही रखता है। इससे प्रतिक्रिया खो जाने के बाद भी Bird उसी ऑपरेशन को पहचान लेता है।
अस्थायी विफलताओं पर यह बैकऑफ़ के साथ फिर से प्रयास करता है और Retry-After का पालन करता है। इसलिए 429 मिलने पर अगले प्रयास से पहले प्रतीक्षा होती है। प्रमाणीकरण और वैलिडेशन की विफलताओं में कारण को आपके एप्लिकेशन को ही ठीक करना होता है।
सूची हेल्पर इटरेशन के दौरान अगले पेज लाते रहते हैं। रीजन रूटिंग आपकी कुंजी के प्रीफ़िक्स से होस्ट चुनती है। वेबहुक हेल्पर डिकोड किया गया इवेंट लौटाने से पहले अनुरोध की मूल बॉडी का सत्यापन करते हैं।
डुप्लिकेट व्यावसायिक कार्रवाइयों को अस्वीकार करना फिर भी आपके एप्लिकेशन का काम है। अपने अधूरे काम को फिर से शुरू करना भी उसी की ज़िम्मेदारी है। Idempotency बताता है कि अनुरोध के फिर से प्रयास और एप्लिकेशन की गारंटी के बीच सीमा कहाँ है।
अगर मेरे ऑपरेशन के लिए कोई टाइप्ड मेथड न हो तो?
जिस सार्वजनिक एंडपॉइंट के लिए अलग टाइप्ड मेथड नहीं है, उसे कॉल करने के लिए SDK के HTTP वर्ब मेथड इस्तेमाल करें।
इन मेथड में भी अनुरोध प्रबंधन बना रहता है, जिसमें फिर से प्रयास और रीजन का चुनाव शामिल है। पाथ और पेलोड आप API संदर्भ से देते हैं।
टाइप्ड मेथड न होने से कोई ऑपरेशन अनुपलब्ध नहीं हो जाता। कॉल करने का मेथड बदलने से यह नहीं बदलता कि आपका क्रेडेंशियल किन एंडपॉइंट तक पहुँच सकता है।
उदाहरण के लिए, API कुंजी रोटेट करें साइन-इन किए हुए CLI या MCP सेशन से, या डैशबोर्ड से। CLI या MCP सर्वर को api_keys:write वाले व्यक्ति से अनुमति चाहिए। केवल API कुंजी रखने वाली सेवा यह नहीं कर सकती।
मुझे HTTP को सीधे कब कॉल करना चाहिए?
जब उपलब्ध SDK आपकी भाषा, रनटाइम या डिपेंडेंसी नीति के अनुकूल न हों, तब सीधे कॉल करें।
क्लाइंट लाइब्रेरी चुनने से पहले किसी एंडपॉइंट को जाँचने के लिए भी आप सीधा अनुरोध भेज सकते हैं। Bird दोनों तरीकों के लिए एक ही सार्वजनिक HTTP API का उपयोग करता है।
अगर आपको किसी दूसरी भाषा में जनरेट किए गए मॉडल चाहिए, तो OpenAPI विनिर्देश से क्लाइंट जनरेट करें। उसके रनटाइम व्यवहार की अलग से जाँच करें, क्योंकि अलग-अलग जनरेटर अलग-अलग चीज़ें लागू करते हैं।
सीधे अनुरोधों के लिए, अपनी कुंजी के क्षेत्र वाला होस्ट चुनें। एक ही ऑपरेशन के हर फिर से प्रयास में वही idempotency कुंजी दोबारा इस्तेमाल करें। पेजिनेशन कर्सर का पालन करें। आने वाले webhook सिग्नेचर को बिना बदले बॉडी पर सत्यापित करें।
फिर से प्रयास करने और टाइमआउट की सीमाएँ तय करें, ताकि कोई विफल होती डिपेंडेंसी आपके एप्लिकेशन के अनुरोध को अनिश्चित समय तक खुला न रख सके।
फिर से प्रयास मेरे टाइमआउट पर कैसे असर डालते हैं?
फिर से प्रयास के कारण पूरी कॉल एक प्रयास के टाइमआउट से ज़्यादा देर तक चल सकती है।
SDK डिफ़ॉल्ट रूप से दो बार फिर से प्रयास करने देते हैं, यानी एक कॉल में अधिकतम तीन प्रयास होते हैं। TypeScript, Python और Go में हर प्रयास का डिफ़ॉल्ट टाइमआउट 60 सेकंड है। इसलिए टाइमआउट होने वाले तीन प्रयास, फिर से प्रयास के बीच के इंतज़ार को जोड़े बिना ही, लगभग तीन मिनट ले सकते हैं।
PHP उस HTTP क्लाइंट पर कॉन्फ़िगर किया गया टाइमआउट इस्तेमाल करता है जिसे आप इंजेक्ट करते हैं। टाइमआउट वहीं सेट करें, ताकि अनुरोध की अवधि सीमित रहे।
फिर से प्रयास के बजट को किसी भी बाहरी समय-सीमा के साथ मिलाकर तय करें। SDK अवधारणा गाइड हर भाषा के लिए कॉन्फ़िगरेशन नाम और प्रति-कॉल ओवरराइड बताती है।
SDK के चारों ओर असीमित फिर से प्रयास वाला लूप न जोड़ें। अलग-अलग SDK कॉल अलग-अलग कुंजियाँ जनरेट करती हैं, जब तक कि आप पूरे ऑपरेशन के लिए एक स्थिर idempotency कुंजी खुद न दें।
मुझे कौन-सा इंटीग्रेशन चुनना चाहिए?
अनुरोध हैंडलिंग का उतना ही हिस्सा चुनें, जितना आपके एप्लिकेशन को खुद संभालना ज़रूरी हो।
- Bird SDK: आपकी भाषा समर्थित है और इसकी डिपेंडेंसी आपके रनटाइम में फिट होती हैं।
- SDK वर्ब मेथड: ऑपरेशन सार्वजनिक है, लेकिन उसके लिए कोई अलग टाइप्ड मेथड नहीं है।
- जनरेट किया गया क्लाइंट: आपको कोई दूसरी भाषा या जनरेशन की अपनी परिपाटियाँ चाहिए।
- सीधा HTTP: आप डिपेंडेंसी पर नियंत्रण रखना और अनुरोध नीति खुद लागू करना चाहते हैं।
संक्षेप में
SDK बार-बार दोहराए जाने वाले अनुरोध संबंधी काम संभालते हैं।
वे idempotency कुंजियाँ, फिर से प्रयास, क्षेत्रीय रूटिंग, पेजिनेशन और वेबहुक सत्यापन संभालते हैं। आपके ऐप्लिकेशन के व्यावसायिक नियम फिर भी उसी की ज़िम्मेदारी रहते हैं।
टाइप्ड मेथड न होने पर भी आपका काम नहीं रुकता।
जो सार्वजनिक ऑपरेशन टाइप्ड मेथड में शामिल नहीं हैं, उनके लिए SDK के HTTP वर्ब मेथड का उपयोग करें। अनुरोध संभालने की सुविधा तब भी लागू रहती है।
ऐप्लिकेशन स्तर पर फिर से प्रयास करते समय एक ही कुंजी रखें।
जब तक आप ऑपरेशन के लिए कुंजी खुद नहीं देते, तब तक SDK की अलग-अलग कॉल अलग-अलग idempotency कुंजियाँ बनाती हैं।
हर प्रयास का समय ध्यान में रखें।
डिफ़ॉल्ट रूप से दो बार फिर से प्रयास करना चालू रहता है। TypeScript, Python और Go हर प्रयास का टाइमआउट अलग से लागू करते हैं। PHP अपने HTTP क्लाइंट के टाइमआउट का उपयोग करता है।