बेस URL और क्षेत्र

Bird API क्षेत्रीय होस्ट से उपलब्ध कराया जाता है। हर अनुरोध सीधे उस क्षेत्र में जाता है जहाँ आपके संगठन का डेटा रखा है। API कोई वैश्विक डेटा-प्लेन URL नहीं देता।

क्षेत्र कोड में भूगोल के लिए दो छोटे अक्षर और उसके बाद एक इंस्टेंस अंक होता है (^[a-z]{2}[0-9]+$)। us1 और eu1 अभी उपलब्ध हैं। यह योजना us2 और ap1 जैसे भविष्य के क्षेत्रों को भी समायोजित करती है, और इसके लिए क्लाइंट में कोई बदलाव नहीं करना पड़ता।

हर संगठन एक क्षेत्र से बंधा होता है

साइनअप के समय हर संगठन को एक क्षेत्र दिया जाता है। क्षेत्र आपकी लोकेशन से पहचाना जाता है। पुष्टि करने से पहले आप इसे बदल सकते हैं, लेकिन v1 में इसके बाद इसे बदला नहीं जा सकता। वर्कस्पेस, API कुंजियाँ, संदेश, प्राप्तकर्ता डेटा और इवेंट लॉग उसी क्षेत्र में रहते हैं। इन्हें कभी दूसरे क्षेत्रों में रेप्लिकेट नहीं किया जाता। इस अलगाव से डेटा-रेज़िडेंसी प्रतिबद्धताएँ पूरी करने में मदद मिलती है, जैसे किसी EU संगठन का डेटा EU में ही स्टोर और प्रोसेस करना।

केवल प्रमाणीकरण और खाता प्रशासन (/v1/auth, /v1/admin) वैश्विक रूप से रेप्लिकेट किए गए डेटा पर काम करते हैं। इसी वजह से इन्हें क्षेत्र-रहित होस्ट platform.bird.com से सर्व किया जाता है।

रूटिंग: कुंजी से होस्ट तय होता है

API कुंजी के प्रीफ़िक्स में उसका क्षेत्र दर्ज होता है: bk_us1_... कुंजियाँ us1 की होती हैं और bk_eu1_... कुंजियाँ eu1 की। हर कुंजी को उससे मेल खाने वाले क्षेत्रीय होस्ट पर भेजें।

अगर कोई अनुरोध गलत क्षेत्र में पहुँचता है, तो उसे आगे भेजने के बजाय 421 Misdirected Request के साथ अस्वीकार कर दिया जाता है। त्रुटि संदेश में सही होस्ट का नाम होता है:

{
  "type": "misdirected_error",
  "code": "E01010",
  "name": "MisdirectedRequest",
  "message": "Organization belongs to region eu1 but this request reached us1. Send the request to eu1.platform.bird.com.",
  "request_id": "..."
}

हर API प्रतिक्रिया में एक X-Bird-Region हेडर भी होता है। इसमें उस क्षेत्र का नाम होता है जिसने अनुरोध को सर्व किया। इससे आप पुष्टि कर सकते हैं कि अनुरोध वास्तव में किस क्षेत्र में पहुँचा।

SDK और CLI अपने-आप रूट करते हैं

आधिकारिक SDK और CLI कुंजी के प्रीफ़िक्स से क्षेत्र पढ़कर होस्ट चुनते हैं। bk_eu1_... कुंजी होने पर हर कॉल बिना किसी कॉन्फ़िगरेशन के eu1.platform.bird.com पर जाती है। टेस्ट एनवायरनमेंट के लिए आप अनुमानित होस्ट को बदल सकते हैं: TypeScript SDK में baseUrl, Go SDK में option.WithBaseURL, या CLI पर --base-url (या BIRD_API_URL) का उपयोग करें।

संबंधित

• प्रमाणीकरण: कुंजी का फ़ॉर्मैट और विफलता की प्रतिक्रियाएँ
• समर्थित देश और प्रतिबंध: डिलीवरी कवरेज और साइनअप के समय डेटा रेज़िडेंसी का चुनाव