रिस्पॉन्स एक्सट्रैक्शन

MirApi आपके ऐप्लिकेशन कोड में कोई बदलाव किए बिना अपस्ट्रीम रिस्पॉन्स से विशिष्ट फ़ील्ड निकाल सकता है और JSON स्ट्रक्चर को नया रूप दे सकता है — या रिस्पॉन्स बॉडी में मिले URL पर रीडायरेक्ट कर सकता है।

रिस्पॉन्स ट्रांसफ़ॉर्मेशन को दो हेडर नियंत्रित करते हैं:

• X-Extract-Redirect — रिस्पॉन्स बॉडी में URL खोजकर उस पर रीडायरेक्ट करता है (302 Found)
• X-Extract-Map — रिस्पॉन्स बॉडी से फ़ील्ड निकालकर उन्हें नए JSON ऑब्जेक्ट में रिनेम करता है

X-Extract-Redirect

JSONPath एक्सप्रेशन (या || के साथ फ़ॉलबैक चेन) का उपयोग करके अपस्ट्रीम रिस्पॉन्स बॉडी से URL निकालता है और उस URL पर 302 Found रीडायरेक्ट जारी करता है।

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

अपस्ट्रीम से सफल रिस्पॉन्स (HTTP स्टेटस कोड 2xx) मिलने पर, प्रॉक्सी रिस्पॉन्स बॉडी का विश्लेषण करता है और निर्दिष्ट JSONPath पर वैल्यू खोजता है। यदि वैल्यू मिलती है, तो प्रॉक्सी क्लाइंट को सामान्य रिस्पॉन्स भेजना बंद करके उस URL पर HTTP 302 Found रीडायरेक्ट लौटाता है।

• फ़ॉलबैक चेन सपोर्ट: एक्सप्रेशन में लॉजिकल OR (||) का उपयोग किया जा सकता है। उदाहरण: X-Extract-Redirect: $.url || $.checkoutUrl || $.data.payment_link। प्रॉक्सी क्रमशः प्रत्येक पाथ जाँचता है और पहली नॉन-एम्प्टी वैल्यू पर रीडायरेक्ट करता है।
• ऑटोमैटिक टाइप कास्टिंग: यदि मिला नोड स्ट्रिंग नहीं है (जैसे नंबर या बूलियन), तो उसे स्वचालित रूप से स्ट्रिंग में बदला जाएगा।
• केवल 2xx पर ट्रिगर होता है: यदि अपस्ट्रीम एरर (400 या 500) लौटाता है, तो कोई रीडायरेक्ट नहीं होगा, जिससे क्लाइंट मूल अपस्ट्रीम एरर रिस्पॉन्स देख सके।

सिंटैक्स नोट्स

फ़ीचर	विवरण
$. प्रीफ़िक्स	वैकल्पिक — यदि छोड़ा जाए तो स्वचालित रूप से जोड़ा जाता है
Array नोटेशन []	समर्थित — मिलान किए गए array एलिमेंट से रीडायरेक्ट URL निकालता है

यह पेमेंट फ्लो के लिए उपयोगी है जहाँ अपस्ट्रीम रिस्पॉन्स बॉडी में चेकआउट URL लौटाता है और आपको यूज़र को वहाँ रीडायरेक्ट करना होता है:

# Upstream returns: {"session_id": "cs_123", "url": "https://checkout.stripe.com/pay/cs_123"}
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/checkout/sessions" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Extract-Redirect: url" \
  -H "Content-Type: application/json" \
  -d '{"mode": "payment", "line_items": [...]}'
# $.  is prepended automatically — same as X-Extract-Redirect: $.url
# → 302 Found
# → Location: https://checkout.stripe.com/pay/cs_123

|| के साथ फ़ॉलबैक चेन

अलग-अलग पेमेंट प्रोवाइडर चेकआउट URL के लिए अलग-अलग फ़ील्ड नाम उपयोग करते हैं। || का उपयोग करके कई पाथ क्रमशः आज़माएँ। प्रत्येक टर्म के लिए $. प्रीफ़िक्स वैकल्पिक है:

# Works across Stripe, Adyen, PayU, and other providers
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.payment-provider.com/sessions" \
  -H "X-Extract-Redirect: url || checkoutUrl || data.payment_link || redirect_url" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd"}'
# MirApi tries each path in order — first non-null value wins
# → 302 Found with the discovered URL

# Works the same with a nested path
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.adyen.com/checkout/v68/sessions" \
  -H "X-Extract-Redirect: action.url || url" \
  -H "Content-Type: application/json" \
  -d '{"amount": {"currency": "EUR", "value": 1000}, "reference": "order-123"}'

Array से एक्सट्रैक्शन

Array के अंदर एलिमेंट से रीडायरेक्ट URL निकालने के लिए [] ब्रैकेट का उपयोग करें:

# Upstream returns: {"data": {"orders": [{"id": "ord_1", "checkout_url": "https://pay.example.com/ord_1"}]}}
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.provider.com/checkout" \
  -H "X-Extract-Redirect: data.orders[].checkout_url" \
  -H "Content-Type: application/json" \
  -d '{"order_ref": "ord_1"}'
# → 302 Found
# → Location: https://pay.example.com/ord_1

उपयोग का मामला: यूनिवर्सल पेमेंट रीडायरेक्ट

एक ऐसा सिंगल एंडपॉइंट बनाएँ जो कई पेमेंट प्रोवाइडर के साथ काम करे — बिना यह जाने कि हर प्रोवाइडर किस फ़ील्ड नाम का उपयोग करता है:

# No matter which provider is in your cascade route, X-Extract-Redirect finds the URL
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: payment-cascade" \
  -H "X-Extract-Redirect: url || checkoutUrl || data.payment_link" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd"}'

X-Extract-Map

रिस्पॉन्स मैपिंग अपस्ट्रीम सर्विस के रिस्पॉन्स JSON को पार्स करता है, JSONPath का उपयोग करके फ़ील्ड निकालता है, और क्लाइंट के लिए एक बिल्कुल नया JSON पेलोड बनाता है। केवल नियमों में स्पष्ट रूप से सूचीबद्ध फ़ील्ड ही लौटाए जाते हैं — अन्य सभी रिस्पॉन्स फ़ील्ड हटा दिए जाते हैं (व्हाइटलिस्ट सिद्धांत)।

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

यह अपस्ट्रीम सर्वर के JSON रिस्पॉन्स को इंटरसेप्ट करता है और क्लाइंट को लौटाने से पहले उसकी स्ट्रक्चर बदल देता है।

मुख्य क्षमताएँ

• कॉमा के साथ मल्टीपल मैपिंग: कॉमा से नियम अलग करके एक साथ कई फ़ील्ड रिनेम/एक्सट्रैक्ट करें।
  • उदाहरण: X-Extract-Map: $.id=>charge_id, $.status=>state
• नेस्टेड स्ट्रक्चर निर्माण: टारगेट की (targetKey) डॉट-नोटेशन को सपोर्ट करती है, जिससे डायनामिक रूप से नेस्टेड JSON ऑब्जेक्ट बनाए जा सकते हैं।
  • उदाहरण: $.id=>data.charge.id से {"data": {"charge": {"id": "..."}}} बनेगा।
• Array/List के साथ काम: खाली ब्रैकेट [] का उपयोग करके ऑब्जेक्ट के पूरे array ट्रांसफ़ॉर्म करें।
  • उदाहरण: provider_data.orders[].order_id=>data.orders[].order
• वैल्यू इंटरपोलेशन: टारगेट की के बाद सिंटैक्स target_key(Template {value}) में टेक्स्ट टेम्पलेट लपेटकर आउटपुट वैल्यू फ़ॉर्मेट करें। JSON कॉन्टेक्स्ट के एक ही नेस्टिंग स्तर से सिब्लिंग फ़ील्ड भी रेफ़रेंस कर सकते हैं।
  • उदाहरण (वैल्यू इंटरपोलेशन): provider_data.order_id=>data.order_text(Order #{value}) ID 123 को {"data":{"order_text":"Order #123"}} में बदलता है।
  • उदाहरण (क्रॉस-फ़ील्ड): status=>status_text(Order {order_id} is {value}) एक ही नेस्टिंग स्तर से order_id फ़ील्ड इंटरपोलेट करेगा।
• सिंगल फ़ील्ड फ़ॉलबैक (बिना =>): यदि आप बिना टारगेट की के JSONPath पास करते हैं (जैसे X-Extract-Map: $.status), तो प्रॉक्सी extracted नाम की डिफ़ॉल्ट की में एक्सट्रैक्टेड वैल्यू के साथ JSON ऑब्जेक्ट लौटाता है।
  • उदाहरण: {"extracted": "success"}

सिंटैक्स ओवरव्यू

=> के बाईं ओर (सोर्स) और दाईं ओर (टारगेट) एक समान सिंटैक्स साझा करते हैं:

फ़ीचर	विवरण
सोर्स पर $. प्रीफ़िक्स	वैकल्पिक — अनुपस्थित होने पर स्वचालित रूप से जोड़ा जाता है
सोर्स पर Array नोटेशन	JSONPath वाइल्डकार्ड [*] के बजाय [] ब्रैकेट का उपयोग करें
नेस्टेड टारगेट की	डॉट-नोटेशन समर्थित (जैसे data.order)
मल्टीपल Array क्वेरी	एलिमेंट इंडेक्स द्वारा एकल array में मर्ज किए जाते हैं
वैल्यू टेम्पलेट {value}	कस्टम स्ट्रिंग के अंदर एक्सट्रैक्टेड वैल्यू फ़ॉर्मेट करता है
क्रॉस-फ़ील्ड टेम्पलेट {field_name}	आउटपुट में एक ही array एलिमेंट के अन्य फ़ील्ड इंटरपोलेट करता है

A. फ़्लैट एक्सट्रैक्शन और मैपिंग

किसी फ़ील्ड को निकालकर नई फ़्लैट की पर मैप करता है। $. प्रीफ़िक्स वैकल्पिक है:

curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.provider.com/orders" \
  -H "X-Extract-Map: provider_data.order_id=>order_id"
# Upstream: {"provider_data": {"order_id": 353454876}}
# Returns:  {"order_id": "353454876"}

# Extract the caller's IP from httpbin
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://httpbin.org/get" \
  -H "X-Extract-Map: $.origin"
# Returns: {"extracted": "93.123.45.67"}

B. नेस्टेड टारगेट जेनरेशन

दाईं ओर डॉट-नोटेशन का उपयोग करके क्लाइंट आउटपुट में नेस्टेड JSON स्ट्रक्चर बनाता है:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.provider.com/orders" \
  -H "X-Extract-Map: provider_data.order_id=>data.order" \
  -H "Content-Type: application/json" \
  -d '{"ref": "ord_999"}'
# Upstream: {"provider_data": {"order_id": 353454876}}
# Returns:  {"data": {"order": "353454876"}}

# Normalize Stripe response
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Extract-Map: $.id=>charge_id, $.status=>payment_status, $.amount=>amount_cents, $.created=>created_at" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'
# Returns: {"charge_id": "ch_3Pz9...", "payment_status": "succeeded", "amount_cents": 2000, "created_at": 1748130000}

C. Array एक्सट्रैक्शन और मैपिंग

अपस्ट्रीम से array निकालकर कस्टम की के अंतर्गत रखता है। प्रत्येक एलिमेंट पर पुनरावृत्ति के लिए [] ब्रैकेट का उपयोग करें:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.provider.com/orders" \
  -H "X-Extract-Map: provider_data.orders[].order_id=>data.orders[].order" \
  -H "Content-Type: application/json" \
  -d '{"customer": "cus_123"}'
# Upstream: {"provider_data": {"orders": [{"order_id": 111}, {"order_id": 222}]}}
# Returns:  {"data": {"orders": [{"order": "111"}, {"order": "222"}]}}

D. मल्टी-फ़ील्ड Array मर्जिंग

एक ही array पाथ को टारगेट करने वाले कई नियम एलिमेंट इंडेक्स द्वारा एकल संयुक्त array में मर्ज किए जाते हैं:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.provider.com/orders" \
  -H "X-Extract-Map: provider_data.orders[].order_id=>data.orders[].order, provider_data.orders[].amount=>data.orders[].sum" \
  -H "Content-Type: application/json" \
  -d '{"customer": "cus_123"}'
# Upstream: {"provider_data": {"orders": [{"order_id": 111, "amount": 100}, {"order_id": 222, "amount": 200}]}}
# Returns:  {"data": {"orders": [{"order": "111", "sum": "100"}, {"order": "222", "sum": "200"}]}}

# AI provider normalization
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: ai-providers" \
  -H "X-Extract-Map: $.choices[0].message.content=>text, $.model=>model_used" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
# Returns: {"text": "Hello! How can I help?", "model_used": "gpt-4o"}

E. वैल्यू टेम्पलेटिंग और क्रॉस-फ़ील्ड Array टेम्पलेटिंग

टारगेट की नाम के बाद कोष्ठक में टेम्पलेट स्ट्रिंग जोड़ें। एक्सट्रैक्टेड फ़ील्ड के प्लेसहोल्डर के रूप में {value} और उसी array एलिमेंट के किसी भी सिब्लिंग फ़ील्ड को रेफ़रेंस करने के लिए {field_name} का उपयोग करें:

# Single-field value template
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.provider.com/orders" \
  -H "X-Extract-Map: provider_data.orders[].order_id=>data.orders[].order_id, provider_data.orders[].status=>data.orders[].status_text(Order {order_id} is {value})" \
  -H "Content-Type: application/json" \
  -d '{"customer": "cus_123"}'
# Upstream: {"provider_data": {"orders": [
#   {"order_id": 111, "status": "success"},
#   {"order_id": 222, "status": "fail"}
# ]}}
# Returns: {"data": {"orders": [
#   {"order_id": "111", "status_text": "Order 111 is success"},
#   {"order_id": "222", "status_text": "Order 222 is fail"}
# ]}}

टेम्पलेट प्लेसहोल्डर नियम:

• {value} — सोर्स फ़ील्ड की एक्सट्रैक्टेड वैल्यू
• {field_name} — एक ही array एलिमेंट में पहले से मैप की गई कोई भी सिब्लिंग फ़ील्ड

दोनों हेडर एक साथ उपयोग करना

X-Extract-Redirect और X-Extract-Map अलग-अलग उद्देश्यों के लिए हैं और एक ही रिक्वेस्ट में एक साथ उपयोग नहीं किए जा सकते। इनमें से किसी एक का उपयोग करें:

हेडर	कब उपयोग करें…	रिस्पॉन्स
X-Extract-Redirect	जब अपस्ट्रीम रीडायरेक्ट के लिए URL लौटाता है	302 Found के साथ Location हेडर
X-Extract-Map	जब आप एक ट्रिम/रिनेम्ड JSON रिस्पॉन्स चाहते हैं	200 OK ट्रांसफ़ॉर्म्ड JSON बॉडी के साथ