क्लाइंट जनरेटर इस्तेमाल करने पर आपको एंडपॉइंट पाथ और अनुरोध फ़ील्ड अपनी लाइब्रेरी में कॉपी नहीं करने पड़ते। यह ऐसे मॉडल भी बना सकता है जो अनुरोध आपके एप्लिकेशन से निकलने से पहले ही गलत इनपुट पकड़ लेते हैं।
Bird का स्पेक कहाँ से मिलेगा?
सार्वजनिक स्पेसिफिकेशन JSON या YAML में डाउनलोड करें।
Bird का API संदर्भ और SDK जनरेटर भी इसी सार्वजनिक बंडल का उपयोग करते हैं। डाउनलोड की गई फ़ाइल को अपने जनरेशन कॉन्फ़िगरेशन के साथ सहेजें, ताकि आप बाद में वही क्लाइंट दोबारा बना सकें।
OpenAPI स्पेसिफिकेशन तय करता है कि पाथ, पैरामीटर, ऑथेंटिकेशन और प्रतिक्रियाओं की संरचना का वर्णन कैसे किया जाए। आपका जनरेटर इसी वर्णन से अपनी लक्ष्य भाषा के लिए मेथड और मॉडल बनाता है।
क्लाइंट कैसे जनरेट करें?
Bird के JSON स्पेक से क्लाइंट बनाने के लिए OpenAPI Generator का उपयोग करें। डाउनलोड, वैलिडेशन और जनरेशन कमांड चलाने से पहले यह टूल इंस्टॉल करें।
यह उदाहरण bird-client में एक Ruby क्लाइंट जनरेट करता है:
curl --fail --location https://bird.com/openapi.json --output bird-openapi.json
openapi-generator-cli validate -i bird-openapi.json
openapi-generator-cli generate -i bird-openapi.json -g ruby -o bird-clientजनरेटर के YAML पार्सर की आकार सीमा से बचने के लिए JSON का उपयोग करें। वैलिडेशन सफल होने पर भी सुझाव दिखा सकता है। जनरेट करने से पहले त्रुटियों की समीक्षा करें।
किसी दूसरी भाषा के लिए ruby की जगह कोई समर्थित जनरेटर रखें। आउटपुट को बिल्ड या इंस्टॉल करने के लिए उस जनरेटर की इंस्टॉलेशन आवश्यकताओं और जनरेट हुई README का पालन करें।
जनरेट की गई फ़ाइलों को हाथ से लिखे एप्लिकेशन कोड से अलग रखें। उस डायरेक्टरी में दोबारा जनरेट करने पर क्लाइंट में सीधे किए गए आपके बदलाव मिट सकते हैं।
जनरेटर की उपयोग गाइड में भाषा विकल्पों और कॉन्फ़िगरेशन फ़ाइलों का विवरण है।
क्लाइंट में कौन-से ऑपरेशन शामिल होंगे?
क्लाइंट में वे HTTP ऑपरेशन शामिल होते हैं जो Bird के सार्वजनिक बंडल में हैं। किसी दूसरी सतह पर मौजूद ऑपरेशन के लिए सार्वजनिक क्लाइंट जनरेट करने से कोई मेथड नहीं बनता।
उदाहरण के लिए, API-कुंजी रोटेशन डैशबोर्ड सेशन या व्यक्तिगत CLI या MCP ग्रांट के ज़रिए उपलब्ध है। यह सार्वजनिक बंडल में नहीं है, और इसे वर्कस्पेस API कुंजी से कॉल नहीं किया जा सकता।
टोल-फ़्री सत्यापन के भी कुछ CLI और MCP ऑपरेशन सार्वजनिक बंडल से बाहर हैं। कोई मेथड न मिलने पर उसे मैन्युअल रूप से लिखने का निर्णय लेने से पहले इन सतहों को जाँचें।
Realtime पब्लिशिंग एक सार्वजनिक HTTP ऑपरेशन है। चैनल इवेंट्स को सब्सक्राइब करने के लिए WebSocket कनेक्शन चाहिए। उस हिस्से के लिए Realtime क्लाइंट का उपयोग करें।
मुझे अनुरोध हैंडलिंग में क्या जाँचना चाहिए?
जो हैंडलिंग जनरेट किए गए रनटाइम में नहीं है, उसे जोड़ने से पहले रनटाइम की जाँच करें। अलग-अलग जनरेटर और कॉन्फ़िगरेशन अलग-अलग व्यवहार देते हैं।
| विषय | क्या जाँचें |
|---|---|
| रीजन | चुना गया होस्ट आपकी कुंजी के प्रीफ़िक्स वाले रीजन से मेल खाता है। |
| आइडेम्पोटेंसी | एक ही राइट के सभी प्रयासों में एक ही कुंजी दोबारा इस्तेमाल होती है। |
| फिर से प्रयास | अस्थायी विफलताओं पर फिर से प्रयास सीमित संख्या में हों और वे Retry-After का पालन करें। |
| पेजिनेशन | इटरेशन तब तक कर्सर का अनुसरण करे जब तक कोई और पेज न बचे। |
| वेबहुक | सत्यापन बिना बदले अनुरोध बॉडी का उपयोग करे और पार्स करने से पहले सिग्नेचर जाँचे। |
जनरेट किया गया पैरामीटर ज़रूरी नहीं कि उसका मान आपके लिए प्रबंधित करे। जब तक रनटाइम कुंजी न दे, तब तक Idempotency-Key फ़ील्ड के लिए सही अवधि वाली कुंजी आपको ही देनी होगी।
इसी तरह, सर्वर क्षेत्र कॉन्फ़िगर किया जा सकता है, इससे यह साबित नहीं होता कि क्लाइंट उसे आपके क्रेडेंशियल से पढ़ता है। अनुरोध भेजने से पहले होस्ट सेट करें या उसकी जाँच करें।
क्या मुझे क्लाइंट जनरेट करना चाहिए या Bird SDK का उपयोग करना चाहिए?
जब Bird SDK की समर्थित भाषा और डिपेंडेंसी आपके एप्लिकेशन के अनुकूल हों, तब उसका उपयोग करें। जब आपको कोई दूसरी भाषा चाहिए या आपके संगठन के अपने जनरेशन नियम हों, तब क्लाइंट जनरेट करें।
SDK या सीधे API कॉल में समर्थित भाषाओं, फिर से प्रयास करने के व्यवहार और डिफ़ॉल्ट टाइमआउट की तुलना की गई है।
- Bird SDK: वह अनुरोध हैंडलिंग इस्तेमाल करें जो Bird देता है और बनाए रखता है।
- जनरेट किया गया क्लाइंट: अपनी भाषा चुनें और डिप्लॉय करने से पहले उसकी रनटाइम हैंडलिंग की समीक्षा करें।
- केवल जनरेट किए गए टाइप: अनुरोध हैंडलिंग को अपनी मौजूदा HTTP लेयर में ही रखें।
संक्षेप में
सार्वजनिक स्पेसिफिकेशन डाउनलोड करें।
Bird एक ही API विवरण को YAML और JSON दोनों में प्रकाशित करता है। JSON फ़ॉर्मेट इस्तेमाल करने पर जनरेटर की YAML आकार सीमा लागू नहीं होती।
अपनी लक्षित भाषा के लिए जनरेट करें।
OpenAPI Generator क्लाइंट जनरेट करने से पहले डाउनलोड की गई JSON को वैलिडेट करता है।
जनरेट किए गए क्लाइंट में अनुरोधों का प्रबंधन जाँचें।
क्लाइंट पर निर्भर होने से पहले रीजन चयन, फिर से प्रयास करना, idempotency, पेजिनेशन और webhook सत्यापन की समीक्षा करें।
जो ऑपरेशन नहीं हैं, उन्हें किसी दूसरे सरफ़ेस पर खोजें।
API कुंजी रोटेशन के लिए डैशबोर्ड सेशन या व्यक्तिगत CLI या MCP ग्रांट चाहिए। Realtime सब्सक्रिप्शन के लिए WebSocket क्लाइंट चाहिए।