SDK की अवधारणाएँ

TypeScript, Go, Python और PHP SDK एक ही डिज़ाइन का पालन करते हैं। हर SDK में एक जनरेट किया गया आधार होता है, जिसमें टाइप और एक निम्न-स्तरीय क्लाइंट होते हैं। ये Bird के OpenAPI विनिर्देश से बनाए जाते हैं। हाथ से लिखी गई एक परत अनुरोध के जीवनचक्र को संभालती है और चुनी हुई सार्वजनिक सतह उपलब्ध कराती है। यह पेज उनका साझा व्यवहार बताता है। हर भाषा के पेज उस भाषा के अनुरूप विवरण बताते हैं।

स्वचालित आइडेम्पोटेंसी

हर बदलाव करने वाले अनुरोध (POST, PUT, PATCH, DELETE) को स्वचालित रूप से जनरेट किया गया Idempotency-Key हेडर मिलता है। यह कुंजी हर तार्किक कॉल के लिए एक बार जनरेट होती है और फिर से प्रयास की हर कोशिश में दोबारा इस्तेमाल होती है। इससे फिर से प्रयास किया गया लेखन दो बार लागू नहीं होता। अगर सर्वर के प्रोसेस करने के बाद भेजने का अनुरोध टाइमआउट हो जाता है, तो फिर से प्रयास करने पर सहेजी गई प्रतिक्रिया मिलती है। जब तार्किक ऑपरेशन एक से ज़्यादा SDK कॉल में फैला हो, तब अपनी कुंजी दें (प्रति-कॉल idempotencyKey / option.WithIdempotencyKey / idempotency_key)। उदाहरण के लिए, SDK के चारों ओर ऐप्लिकेशन का फिर से प्रयास करने वाला लूप। सर्वर-साइड प्रोटोकॉल के लिए आइडेम्पोटेंसी देखें।

सुरक्षित रूप से फिर से प्रयास करना

फिर से प्रयास करना डिफ़ॉल्ट रूप से चालू रहता है (हर SDK में maxRetries: 2)। क्लाइंट अस्थायी विफलताओं पर फिर से प्रयास करता है, जैसे नेटवर्क त्रुटियाँ, प्रति-प्रयास टाइमआउट, 429 प्रतिक्रियाएँ और फिर से प्रयास योग्य 5xx प्रतिक्रियाएँ। यह जिटर वाले एक्सपोनेंशियल बैकऑफ़ का उपयोग करता है और सर्वर के Retry-After हेडर का पालन करता है। निश्चित विफलताओं (401, 404, 422 और अन्य 4xx प्रतिक्रियाओं) पर कभी फिर से प्रयास नहीं किया जाता। आइडेम्पोटेंसी कुंजी के दोबारा इस्तेमाल से बदलाव वाले अनुरोधों पर फिर से प्रयास करना सुरक्षित रहता है। टाइमआउट हर प्रयास पर लागू होता है (डिफ़ॉल्ट रूप से 60 सेकंड), इसलिए फिर से प्रयास वाली कॉल में ज़्यादा समय लग सकता है। PHP इंजेक्ट किए गए HTTP क्लाइंट का टाइमआउट इस्तेमाल करता है, क्योंकि PSR-18 में हर अनुरोध के लिए पोर्टेबल टाइमआउट नहीं है।

पेजिनेशन

सूची वाले एंडपॉइंट कर्सर से पेजिनेट होते हैं। हर SDK नेटिव इटरेशन का समर्थन करता है, जो अगले पेज अपने-आप लाता है। कर्सर को खुद नियंत्रित करने के लिए एकल-पेज एक्सेसर का उपयोग करें। हर पेज में data और next_cursor होते हैं; आगे बढ़ने के लिए कर्सर को starting_after के रूप में वापस दें।

for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor

for message in client.email.list(status="delivered"):
    print(message.id)
page = client.email.list(status="delivered")  # page.data, page.next_cursor
print(len(page.data), page.next_cursor)

for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusBounced}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id)
}
page, err := client.Email.ListPage(context.Background(), bird.EmailListParams{}, "")
if err != nil {
	log.Fatal(err)
}
fmt.Println(len(page.Data)) // page.NextCursor carries the next starting_after

$page = $bird->email->list(['status' => 'delivered'])->fetch();
foreach ($page->data as $message) {
    echo $message->getId(), "\n";
}
$next = $page->nextCursor; // pass back as starting_after to fetch the next page

कर्सर, limit और include_total के लिए पेजिनेशन संदर्भ देखें।

क्षेत्र का अनुमान

Bird API कुंजियों में उनका क्षेत्र दर्ज होता है: bk_{region}_{token}। SDK उपसर्ग पढ़ता है और अनुरोधों को अपने आप https://{region}.platform.bird.com पर भेजता है। region विकल्प अनुमानित क्षेत्र को बदल देता है। स्पष्ट रूप से दिया गया baseUrl (option.WithBaseURL / base_url) इन दोनों पर प्राथमिकता रखता है और स्थानीय विकास या सेल्फ़-होस्टेड परिनियोजन में काम आता है। अगर कुंजी bk_{region}_ प्रारूप से मेल नहीं खाती और कोई ओवरराइड सेट नहीं है, तो क्लाइंट बनाना विफल हो जाता है।

प्रति-कॉल विकल्प बनाम केवल निर्माण के समय का कॉन्फ़िगरेशन

कॉन्फ़िगरेशन के दो स्तर हैं। पहचान और ट्रांसपोर्ट सेटिंग्स केवल क्लाइंट बनाते समय सेट होती हैं: API कुंजी, बेस URL या क्षेत्र, और HTTP क्लाइंट या fetch इम्प्लीमेंटेशन। लाइफ़साइकल सेटिंग्स को निर्माण के समय डिफ़ॉल्ट के रूप में सेट किया जा सकता है और हर कॉल में बदला जा सकता है: timeout, maxRetries, इडेम्पोटेंसी कुंजी और अतिरिक्त हेडर। TypeScript, Python और PHP अंत में एक विकल्प ऑब्जेक्ट लेते हैं; Go वेरिएडिक option.With… विकल्प लेता है। SDK के अपने हेडर (Authorization, User-Agent, Idempotency-Key) कॉल करने वाले के दिए हेडर पर प्राथमिकता रखते हैं। चैनल डिफ़ॉल्ट, जैसे ईमेल का डिफ़ॉल्ट from, भी इसी तरह काम करते हैं।

वेबहुक सत्यापन

हर SDK सत्यापन के लिए एक ही एंट्री पॉइंट देता है: webhooks.unwrap(rawBody, headers)। यह Standard Webhooks लागू करता है, जिसमें मूल पेलोड और आपके एंडपॉइंट के साइनिंग सीक्रेट पर HMAC-SHA256 का उपयोग होता है। यह v1 टैग वाली सिग्नेचर प्रविष्टियाँ स्वीकार करता है, 5 मिनट की सहनशीलता सीमा से बाहर के टाइमस्टैम्प अस्वीकार करता है, और सिग्नेचर की तुलना स्थिर समय में करता है। अनुरोध के मूल बॉडी बाइट ठीक वैसे ही दें जैसे वे प्राप्त हुए। JSON को पार्स करके दोबारा सीरियलाइज़ करने से बाइट बदल जाते हैं और सिग्नेचर अमान्य हो जाता है।

सफल होने पर unwrap एक टाइप्ड इवेंट लौटाता है, जिसका प्रकार type से तय होता है, जैसे email.delivered या email.bounced। अज्ञात इवेंट प्रकार भी सत्यापित और डिकोड होते हैं, इसलिए उन्हें अपनी default शाखा में संभालें। सत्यापन विफल होने पर एक अलग त्रुटि मिलती है (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); इसके जवाब में 400 लौटाएँ। एंडपॉइंट सेटअप और इवेंट कैटलॉग के लिए वेबहुक देखें।

अगले कदम

• क्विकस्टार्ट: अपनी भाषा और फ़्रेमवर्क में अपना पहला ईमेल भेजें।
• वेबहुक और इवेंट: एक एंडपॉइंट सेट करें और unwrap के पीछे का इवेंट कैटलॉग देखें।
• API संदर्भ: हर SDK द्वारा उपयोग किया जाने वाला HTTP अनुबंध देखें।