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

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 हेडर भी होता है जो उस क्षेत्र का नाम बताता है जिसने सर्व किया, यह पुष्टि करने में उपयोगी है कि अनुरोध वास्तव में किस क्षेत्र में पहुँचा।

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