मल्टी-टारगेट कैस्केड रूटिंग

कैस्केड रूटिंग आपको एक ही अनुरोध के लिए कई अपस्ट्रीम टारगेट परिभाषित करने देता है। MirApi उन्हें अनुक्रम (Priority) या एक साथ (Race) में आज़माएगा, और पहला सफल रिस्पॉन्स लौटाएगा।

कैस्केड रूट आपके डैशबोर्ड में कॉन्फ़िगर किए जाते हैं और X-Route-Key हेडर का उपयोग करके सक्रिय किए जाते हैं।

डैशबोर्ड में रूट कॉन्फ़िगर करें

कैस्केड रूटिंग का उपयोग करने से पहले, अपने MirApi डैशबोर्ड में एक रूट बनाएं:

1. Routes → Create Route खोलें
2. एक नाम सेट करें (उदा. ai-providers)
3. टारगेट जोड़ें (उदा. https://api.openai.com/v1/chat/completions, https://api.anthropic.com/v1/messages)
4. स्ट्रेटेजी चुनें: Priority या Race
5. प्रति-टारगेट टाइमआउट सेट करें (ms में)
6. वैकल्पिक रूप से बॉडी मैपिंग और रिस्पॉन्स एक्सट्रैक्शन नियम कॉन्फ़िगर करें

रूट सक्रिय करें

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: ai-providers" \
  -H "X-Identity-Key: Bearer $OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

कैस्केड स्ट्रेटेजी (Cascade Strategies)

Priority (क्रमिक फ़ेलओवर)

टारगेट को क्रम से आज़माया जाता है। अगला टारगेट केवल तभी आज़माया जाता है जब पिछला टारगेट विफल हो जाता है (5xx, टाइमआउट, या कनेक्शन त्रुटि)।

टारगेट 1: https://api.openai.com/...  → विफल (503)
टारगेट 2: https://api.anthropic.com/... → विफल (टाइमआउट)
टारगेट 3: https://api.groq.com/...   → सफल ✓

प्रतिक्रिया: X-Rescued: cascade_fallback

Race (समानांतर)

सभी टारगेट को एक साथ कॉल किया जाता है। सबसे तेज़ सफल प्रतिक्रिया जीतती है; अन्य को रद्द कर दिया जाता है।

---

टारगेट अनुरोध बॉडी मैपिंग (Target Request Body Mapping)

कैस्केड रूट में विभिन्न एंडपॉइंट अक्सर JSON अनुरोध बॉडी में अलग-अलग फ़ील्ड नामों की अपेक्षा करते हैं। अपने क्लाइंट कोड को बदले बिना इसे संभालने के लिए, प्रत्येक कैस्केड टारगेट डेटाबेस में एक body_map को परिभाषित कर सकता है।

मैपिंग नियम का प्रारूप अल्पविराम से अलग की गई सूची है: original_field=>new_field।

यह कैसे काम करता है:

1. आपका क्लाइंट मूल JSON संरचना के साथ प्रॉक्सी गेटवे को अनुरोध भेजता है।
2. गेटवे बॉडी को इंटरसेप्ट करता है और उसे टारगेट पर फॉरवर्ड करने से पहले, उस टारगेट के body_map नियम के अनुसार मिलान की गई कुंजियों का नाम बदल देता है।

उदाहरण परिदृश्य: आपका एप्लिकेशन एक चार्ज अनुरोध भेजता है:

{
  "amount": 9900,
  "currency": "usd",
  "customer_id": "cus_123"
}

• टारगेट 1 (Stripe) amount और currency की अपेक्षा करता है। कोई मैपिंग परिभाषित नहीं है।
• टारगेट 2 (वैकल्पिक गेटवे) amount के स्थान पर sum और currency के स्थान पर cur की अपेक्षा करता है।
  • कॉन्फ़िगर किया गया body_map: amount=>sum, currency=>cur
  • अपस्ट्रीम को मिलता है: {"sum": 9900, "cur": "usd", "customer_id": "cus_123"}

---

कस्टम बॉडी फॉलबैक स्थितियां (Custom Body Fallback Conditions)

डिफ़ॉल्ट रूप से, कैस्केड रूटिंग अगले फॉलबैक को केवल तभी ट्रिगर करता है जब कोई टारगेट एंडपॉइंट 5xx स्टेटस कोड लौटाता है, टाइमआउट हो जाता है, या नेटवर्क त्रुटियों का सामना करता है।

हालाँकि, कई API (विशेष रूप से भुगतान गेटवे) लेन-देन अस्वीकृत या विफल होने पर भी 200 OK स्थिति लौटाते हैं। व्यावसायिक तर्क विफलताओं पर रूटिंग का समर्थन करने के लिए, प्रत्येक रूट टारगेट डैशबोर्ड/डेटाबेस में दो मापदंडों का उपयोग करके एक कस्टम फॉलबैक स्थिति परिभाषित कर सकता है:

• fallback_field: प्रतिक्रिया JSON में जांचे जाने वाले फ़ील्ड को इंगित करने वाला एक JSONPath अभिव्यक्ति (उदा. $.status, $.error.code)।
• fallback_value: मिलान करने के लिए एक स्ट्रिंग मान (केस-असंवेदनशील सबस्ट्रिंग जांच)।

यह कैसे काम करता है:

1. टारगेट एंडपॉइंट सफल स्थिति कोड (500 से कम) के साथ प्रतिक्रिया करता है।
2. गेटवे प्रतिक्रिया बॉडी को पढ़ता है और JSONPath का उपयोग करके fallback_field से मान निकालता।
3. यदि निकाले गए मान में सबस्ट्रिंग के रूप में fallback_value शामिल है, तो गेटवे प्रतिक्रिया को विफलता के रूप में मानता है।
4. गेटवे प्रतिक्रिया को खारिज कर देता है, फॉलबैक ट्रिगर को लॉग करता है, और तुरंत कैस्केड श्रृंखला में अगले टारगेट पर वापस आ जाता है।

उदाहरण: भुगतान अस्वीकृत फ़ॉलबैक (Payment Declined Fallback)

एक अपस्ट्रीम भुगतान प्रोसेसर 200 OK लौटाता है लेकिन भुगतान अस्वीकृत कर देता है:

{
  "transaction_id": "tx_abc123",
  "status": "declined",
  "failure_reason": "insufficient_funds"
}

टारगेट को कॉन्फ़िगर करके:

• Fallback Field: $.status
• Fallback Value: declined

GateWay 200 OK को इंटरसेप्ट करता है, देखता है कि $.status "declined" के बराबर है, इसे एक विफलता के रूप में मानता है, और आपके कैस्केड में अगले बैकअप बैंक टारगेट पर भुगतान अनुरोध रूट करता है।

---

लूप रोकथाम रणनीति (Anti-Loop Protection)

गेटवे अपने स्वयं के IP पतों और होस्टनामों के विरुद्ध सभी टारगेट URL को मान्य करता है। कोई भी टारगेट URL जो प्रॉक्सी को ही संदर्भित करता है, अनंत अनुरोध लूप को रोकने के लिए 400 Bad Request के साथ खारिज कर दिया जाता है।

कैस्केड के लिए प्रतिक्रिया हेडर (Response Headers for Cascade)

जब एक गैर-प्राथमिक (non-primary) टारगेट का उपयोग किया जाता है, तो प्रतिक्रिया में शामिल होता है:

HTTP/1.1 200 OK
X-Rescued: cascade_fallback

यदि प्राथमिक टारगेट (सूची में पहला) सफल होता है, तो कोई X-Rescued हेडर नहीं जोड़ा जाता है।