Client जनरेटर आपको endpoint paths और request fields को अपनी लाइब्रेरी में मैन्युअली कॉपी करने से बचाता है। यह ऐसे models भी बना सकता है जो गलत इनपुट को request भेजने से पहले ही पकड़ लेते हैं।
Bird का spec कहाँ से मिलेगा?
पब्लिक स्पेसिफ़िकेशन JSON या YAML में डाउनलोड करें।
Bird का API रेफ़रेंस और SDK जनरेटर भी इसी पब्लिक बंडल का उपयोग करते हैं। डाउनलोड की गई फ़ाइल को अपने जनरेशन कॉन्फ़िगरेशन के साथ सेव करें ताकि बाद में client दोबारा बनाया जा सके।
OpenAPI specification परिभाषित करती है कि paths, parameters, authentication और response shapes कैसे वर्णित किए जाते हैं। आपका जनरेटर इसी विवरण से अपनी लक्षित भाषा के लिए methods और models बनाता है।
Client कैसे जनरेट करें?
Bird के JSON spec से client बनाने के लिए OpenAPI Generator का उपयोग करें। डाउनलोड, वैलिडेशन और जनरेशन कमांड चलाने से पहले टूल इंस्टॉल करें।
यह उदाहरण bird-client में एक Ruby client जनरेट करता है:
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 parser साइज़ सीमा से बचने के लिए JSON का उपयोग करें। वैलिडेशन सफल होने पर भी सुझाव प्रिंट कर सकता है। जनरेट करने से पहले errors की समीक्षा करें।
किसी अन्य भाषा के लिए ruby को किसी सपोर्टेड जनरेटर से बदलें। उस जनरेटर की इंस्टॉलेशन आवश्यकताओं और जनरेट किए गए README का पालन करके output बिल्ड या इंस्टॉल करें।
जनरेट की गई फ़ाइलों को हाथ से लिखे गए एप्लिकेशन कोड से अलग रखें। उसी डायरेक्टरी में दोबारा जनरेट करने पर client में सीधे किए गए बदलाव ओवरराइट हो सकते हैं।
जनरेटर की उपयोग गाइड में भाषा विकल्प और कॉन्फ़िगरेशन फ़ाइलें दस्तावेज़ित हैं।
Client किन operations को कवर करेगा?
Client Bird के पब्लिक बंडल में शामिल HTTP operations को कवर करता है। किसी अन्य surface पर मौजूद operation को पब्लिक-client जनरेशन से method नहीं मिलेगा।
उदाहरण के लिए, API-key रोटेशन डैशबोर्ड सेशन या व्यक्तिगत CLI या MCP grant के ज़रिए उपलब्ध है। यह पब्लिक बंडल में नहीं है और वर्कस्पेस API key से कॉल नहीं किया जा सकता।
टोल-फ़्री सत्यापन में भी पब्लिक बंडल के बाहर CLI और MCP operations हैं। यह निष्कर्ष निकालने से पहले कि किसी अनुपस्थित method के लिए मैन्युअल काम ज़रूरी है, उन surfaces को जाँचें।
Realtime publishing एक पब्लिक HTTP operation है। चैनल इवेंट्स की सब्सक्रिप्शन के लिए WebSocket कनेक्शन चाहिए। उस हिस्से के लिए Realtime client का उपयोग करें।
कौन-सी request handling जाँचनी चाहिए?
जो handling उपलब्ध नहीं है उसे जोड़ने से पहले जनरेट किए गए runtime की जाँच करें। अलग-अलग जनरेटर और कॉन्फ़िगरेशन अलग-अलग व्यवहार प्रदान करते हैं।
| विषय | क्या सत्यापित करें |
|---|---|
| Region | चयनित host आपकी key के prefix में मौजूद region से मेल खाता है। |
| Idempotency | एक ही write के सभी प्रयासों में एक ही key दोबारा उपयोग होती है। |
| फिर से प्रयास | अस्थायी विफलताओं पर सीमित फिर से प्रयास होते हैं जो Retry-After का सम्मान करते हैं। |
| Pagination | Iteration cursors का अनुसरण करता है जब तक कोई अगला page शेष न रहे। |
| Webhooks | सत्यापन अपरिवर्तित request body का उपयोग करता है और parsing से पहले signature जाँचता है। |
जनरेट किया गया parameter ज़रूरी नहीं कि अपना मान स्वयं प्रबंधित करे। Idempotency-Key field के लिए तब भी सही lifetime वाली key चाहिए, जब तक कि runtime स्वयं एक प्रदान न करे।
इसी तरह, कॉन्फ़िगर किया जा सकने वाला server region यह साबित नहीं करता कि client इसे आपके credential से पढ़ता है। Request करने से पहले host सेट या सत्यापित करें।
Client जनरेट करें या Bird SDK का उपयोग करें?
Bird SDK का उपयोग करें जब इसकी सपोर्टेड भाषा और dependencies आपके एप्लिकेशन में फ़िट हों। Client तब जनरेट करें जब आपको कोई अन्य भाषा या आपके संगठन के जनरेशन conventions चाहिए।
SDK या सीधे API कॉल सपोर्टेड भाषाओं, फिर से प्रयास व्यवहार और timeout defaults की तुलना करता है।
- Bird SDK: Bird द्वारा प्रदान और रखरखाव की जाने वाली request handling का उपयोग करें।
- Generated client: अपनी भाषा चुनें और deployment से पहले इसकी runtime handling की समीक्षा करें।
- Generated types only: अपनी मौजूदा HTTP लेयर में request handling बनाए रखें।
संक्षेप में
पब्लिक स्पेसिफ़िकेशन डाउनलोड करें।
Bird एक ही API विवरण को YAML और JSON दोनों में प्रकाशित करता है। JSON फ़ॉर्मेट जनरेटर की YAML साइज़ सीमा से बचाता है।
अपनी लक्षित भाषा के लिए जनरेट करें।
OpenAPI Generator डाउनलोड की गई JSON को वैलिडेट करता है और उसके बाद client जनरेट करता है।
जनरेट की गई request handling जाँचें।
Client पर निर्भर होने से पहले region चयन, फिर से प्रयास, idempotency, pagination और webhook सत्यापन की समीक्षा करें।
छूटे हुए operations के लिए अन्य surface जाँचें।
API-key रोटेशन डैशबोर्ड सेशन या व्यक्तिगत CLI या MCP grant के ज़रिए उपलब्ध है। Realtime सब्सक्रिप्शन के लिए WebSocket client चाहिए।