हेडर संदर्भ मार्गदर्शिका

संकेत

इस पृष्ठ पर सूचीबद्ध प्रत्येक हेडर का एक URL क्वेरी पैरामीटर समतुल्य है। यदि आप किसी ऐसे तृतीय-पक्ष वेबहुक प्रोड्यूसर (Shopify, GitHub, Stripe) को कॉन्फ़िगर कर रहे हैं जो कस्टम हेडर की अनुमति नहीं देता, तो URL क्वेरी पैरामीटर कॉन्फ़िगरेशन मार्गदर्शिका देखें।

MirApi Gateway द्वारा समर्थित सभी X-* कंट्रोल हेडर का पूर्ण संदर्भ। ये हेडर गेटवे द्वारा प्रत्येक अनुरोध पर पढ़े जाते हैं और अपस्ट्रीम API को फॉरवर्ड करने से पहले हटा दिए जाते हैं — इसलिए अपस्ट्रीम इन्हें कभी नहीं देखता।

---

प्रमाणीकरण (Authentication)

X-MirApi-Key

प्रत्येक अनुरोध पर आवश्यक।

आपकी MirApi API कुंजी। गेटवे इसके SHA-256 हैश का उपयोग करके इसे Redis कैश के विरुद्ध सत्यापित करता है। कैश मिस होने पर, यह PostgreSQL डेटाबेस पर वापस आ जाता है। यदि गायब या अमान्य है, तो 401 Unauthorized लौटाता है।

curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: la_5fa62960e7c9af7c***" \
  -H "X-Target-URL: https://httpbin.org/get"

---

रूटिंग (Routing)

X-Target-URL

आवश्यक (जब तक X-Route-Key का उपयोग न किया जाए)।

अनुरोध को फॉरवर्ड करने के लिए अपस्ट्रीम API एंडपॉइंट का पूर्ण URL। इसमें स्कीम (https://) और होस्ट शामिल होना चाहिए। गेटवे URL को सत्यापित करता है और स्वयं की ओर किसी भी गोलाकार संदर्भ को ब्लॉक करता है।

# Basic GET proxy
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges"

# POST with body
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.openai.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

X-Route-Key

X-Target-URL के बजाय अपने डैशबोर्ड से पूर्व-कॉन्फ़िगर किए गए रूट का उपयोग करें। रूट टारगेट URL, फ़ेलओवर टारगेट, टाइमआउट, बॉडी मैपिंग और रिस्पॉन्स एक्सट्रैक्शन नियमों को संग्रहीत करता है — इनमें से किसी को भी आपके अनुरोध हेडर में रखने की आवश्यकता नहीं है।

# Use a route named "payment-primary"
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: payment-primary" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd"}'

# Use a route with identity key for auth
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: ai-cascade" \
  -H "X-Identity-Key: Bearer sk_live_..."

जब किसी रूट में एकाधिक टारगेट होते हैं, तो डैशबोर्ड में परिभाषित कैस्केड रणनीति (priority या race) निर्धारित करती है कि उन्हें कैसे आज़माया जाएगा।

---

क्रेडेंशियल ऑफलोडिंग (Secret Offloading)

X-Identity-Key

इसके मान को अपस्ट्रीम API में Authorization हेडर के रूप में फॉरवर्ड करता है। यह कुंजी अनुरोध की अवधि के लिए केवल मेमोरी में पढ़ी जाती है और कभी भी लॉग या स्थायी स्टोरेज में सहेजी नहीं जाती है।

# Pass a Stripe key to upstream without it appearing in your logs
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_xxxxxxxxxxxxxxxxxxxx" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'

# Pass an OpenAI key
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.openai.com/v1/chat/completions" \
  -H "X-Identity-Key: Bearer sk-proj-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [...]}'

Stripe को प्राप्त होता है: Authorization: Bearer sk_live_xxxx
आपके लॉग में दिखता है: कुंजी की सामग्री के बारे में कुछ नहीं

X-Proxy-Master-Key

डेटाबेस में एन्क्रिप्टेड रूप से संग्रहीत क्रेडेंशियल के लिए डिक्रिप्शन पासफ्रेज। गेटवे AES-GCM का उपयोग करके मिलान किए गए क्रेडेंशियल को डिक्रिप्ट करता है और फॉरवर्ड करने से पहले इसे Authorization के रूप में इंजेक्ट करता है।

कैस्केड रूटिंग (X-Route-Key) के लिए, इस कुंजी का उपयोग एज (Edge) पर सक्रिय टारगेट पर अनुरोध भेजने से पहले टारगेट-विशिष्ट क्रेडेंशियल (credential_id) को गतिशील रूप से डिक्रिप्ट करने के लिए भी किया जाता है।

# Credential is matched by the host of X-Target-URL (e.g., "api.stripe.com" matches a credential named "stripe")
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-Proxy-Master-Key: my-encryption-passphrase" \
  -d '{"amount": 2000, "currency": "usd"}'

# Explicit credential selection by UUID (when you have multiple credentials for the same host)
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-Proxy-Master-Key: my-encryption-passphrase" \
  -H "X-Credential-ID: 4a2e5d18-df99-4d66-a212-3cb5d9f0f9b3" \
  -d '{"amount": 2000, "currency": "usd"}'

X-Credential-ID

X-Proxy-Master-Key के साथ उपयोग करने के लिए विशिष्ट क्रेडेंशियल रिकॉर्ड की वैकल्पिक UUID। यदि छोड़ दिया जाता है, तो गेटवे अपस्ट्रीम होस्टनाम सबस्ट्रिंग द्वारा क्रेडेंशियल का मिलान करता है।

X-Proxy-Auth-Header

वैकल्पिक (X-Proxy-Master-Key के साथ उपयोग किया जाता है)।

उस टारगेट HTTP हेडर के नाम को ओवरराइड करता है जहां डिक्रिप्टेड क्रेडेंशियल इंजेक्ट किया जाता है। डिफ़ॉल्ट: Authorization।

# Inject decrypted secret into X-API-Key header instead of Authorization
curl -X POST https://proxy.mirapi.io/v1/messages \
  -H "X-Target-URL: https://api.anthropic.com/v1/messages" \
  -H "X-Proxy-Master-Key: my-decryption-passphrase" \
  -H "X-Proxy-Auth-Header: X-API-Key" \
  -H "X-Proxy-Auth-Template: {{secret}}"

X-Proxy-Auth-Template

वैकल्पिक (X-Proxy-Master-Key के साथ उपयोग किया जाता है)।

इंजेक्ट किए जाने वाले प्राधिकरण मान का प्रारूप परिभाषित करता है, {{secret}} प्लेसहोल्डर को डिक्रिप्टेड क्रेडेंशियल से बदल दिया जाता है। डिफ़ॉल्ट: Bearer {{secret}}।

# Inject decrypted secret with Basic schema instead of Bearer schema
curl -X GET https://proxy.mirapi.io/v1/accounts \
  -H "X-Target-URL: https://api.somebank.com/v1/accounts" \
  -H "X-Proxy-Master-Key: my-decryption-passphrase" \
  -H "X-Proxy-Auth-Template: Basic {{secret}}"

---

लचीलापन और विश्वसनीयता (Resilience)

X-Proxy-Timeout

क्लाइंट के HTTP लेनदेन की कुल अवधि पर सख्त सीमा (सभी कनेक्शन प्रयासों और घातीय बैकऑफ़ विलंबों सहित)। यदि संपूर्ण निष्पादन इस सीमा से अधिक हो जाता है, तो गेटवे रद्द करता है और 502 Bad Gateway (या 504 Gateway Timeout) के साथ प्रतिक्रिया करता है।

Go duration string स्वीकार करता है: 500ms, 1s, 5s, 30s। डिफ़ॉल्ट: 30s (अधिकतम 30 सेकंड तक सीमित)।

# Tight 2-second overall timeout with 3 retries
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Proxy-Timeout: 2s" \
  -H "X-Retry-Count: 3"

# Generous 30-second overall timeout for a slow upstream
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.slowprovider.com/process" \
  -H "X-Proxy-Timeout: 30s"

X-Attempt-Timeout

अपस्ट्रीम सेवा से किए गए प्रत्येक व्यक्तिगत कनेक्शन प्रयास पर लागू टाइमआउट सीमा। यदि कोई व्यक्तिगत कॉल इस सीमा से अधिक हो जाती है, तो इसे विफलता माना जाता है और अगला रिट्राय प्रयास सक्रिय होता है (यदि रिट्राय कॉन्फ़िगर किए गए हैं)।

Go duration string स्वीकार करता है (जैसे, 200ms, 1s, 5s)। डिफ़ॉल्ट: यदि निर्दिष्ट नहीं है, तो X-Proxy-Timeout के मान पर वापस आ जाता है।

# Individual attempt limit of 1s, total execution time cap of 5s
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Proxy-Timeout: 5s" \
  -H "X-Attempt-Timeout: 1s" \
  -H "X-Retry-Count: 3"

X-Retry-Count

विफलता (5xx स्टेटस या कनेक्शन एरर) पर अतिरिक्त रिट्राय प्रयासों की संख्या। डिफ़ॉल्ट: 0 (कोई रिट्राय नहीं)।

X-Retry-Delay

रिट्राय प्रयासों के बीच का बेस विलंब। गेटवे जिटर के साथ घातीय बैकऑफ़ का उपयोग करता है: प्रत्येक रिट्राय base_delay * 2^attempt + random_jitter (50% तक) प्रतीक्षा करता है, अधिकतम 10 सेकंड।

Go duration string स्वीकार करता है: 100ms, 500ms, 1s। डिफ़ॉल्ट: 100ms।

# 3 retries, starting at 200ms delay with 1s attempt timeout and 5s overall timeout
# Attempt 1: wait ~200ms
# Attempt 2: wait ~400ms + jitter
# Attempt 3: wait ~800ms + jitter
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-Retry-Count: 3" \
  -H "X-Retry-Delay: 200ms" \
  -H "X-Proxy-Timeout: 5s" \
  -H "X-Attempt-Timeout: 1s" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'

# Aggressive retry for an unreliable third-party API
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.bankapi.com/transfer" \
  -H "X-Retry-Count: 5" \
  -H "X-Retry-Delay: 500ms" \
  -H "X-Proxy-Timeout: 10s" \
  -H "X-Attempt-Timeout: 2s"

X-Circuit-Breaker

टारगेट होस्ट के लिए सर्किट ब्रेकर सक्षम करता है। मान: on या true।

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

• गेटवे Redis में प्रति टारगेट होस्ट विफलताओं को ट्रैक करता है।
• 1 मिनट में 5 लगातार विफलताओं के बाद, सर्किट खुल जाता है (स्थिति: OPEN)।
• OPEN रहते हुए, उस होस्ट के नए अनुरोध तुरंत ब्लॉक हो जाते हैं।
• सर्किट 15 सेकंड के बाद स्वतः रीसेट होता है (एक प्रोब अनुरोध के साथ)।
• सफलता पर, सर्किट रीसेट हो जाता है (स्थिति: CLOSED)।

# Enable circuit breaker — protect against a flaky payment gateway
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-Circuit-Breaker: on" \
  -H "X-Smart-Cache: 300s" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'
# If Stripe is down and circuit is OPEN:
# → Smart Cache serves last successful response
# → Response includes: X-Rescued: cache

# Combine with failover for maximum resilience
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://primary-bank.com/pay" \
  -H "X-Circuit-Breaker: on" \
  -H "X-Failover-URL: https://backup-bank.com/pay" \
  -H "X-Retry-Count: 2"

X-Smart-Cache

निर्दिष्ट अवधि के लिए Redis में सबसे हालिया सफल अपस्ट्रीम प्रतिक्रिया को कैश करता है। जब अपस्ट्रीम विफल हो जाता है (सभी रिट्राय के बाद), एरर की बजाय कैश की गई प्रतिक्रिया लौटाई जाती है।

कैश कुंजी इस से गणना की जाती है: SHA256(ClientID + TargetURL + Method + Body) — इसलिए अलग-अलग अनुरोध बॉडी अलग-अलग कैश एंट्री उत्पन्न करती हैं।

Go duration string स्वीकार करता है: 60s, 5m, 1h।

# Cache exchange rates for 5 minutes — if the rates API goes down, serve last known rates
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.exchangerate.host/latest" \
  -H "X-Smart-Cache: 300s"

# Cache product catalog for 10 minutes
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.yourstore.com/v1/products" \
  -H "X-Smart-Cache: 10m" \
  -H "X-Retry-Count: 2"

# Cache + circuit breaker: serve cache when circuit is open
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.openai.com/v1/embeddings" \
  -H "X-Identity-Key: Bearer sk-proj-..." \
  -H "X-Smart-Cache: 3600s" \
  -H "X-Circuit-Breaker: on" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello world", "model": "text-embedding-3-small"}'

महत्वपूर्ण: स्मार्ट कैश केवल एक विफलता फ़ॉलबैक है — यह सफल अनुरोधों के लिए कैश की गई प्रतिक्रियाएँ नहीं देता। प्रत्येक अनुरोध हमेशा पहले अपस्ट्रीम को आज़माता है। कैश किया गया डेटा केवल तभी लौटाया जाता है जब सभी प्रयास विफल हो जाते हैं।

X-Failover-URL

यदि प्राथमिक URL (X-Target-URL) सभी रिट्राय के बाद विफल हो जाता है, तो एक द्वितीयक अपस्ट्रीम URL जिसे आज़माया जाएगा। जब फ़ेलओवर एंडपॉइंट सफलतापूर्वक प्रतिक्रिया देता है, तो रिस्पॉन्स में X-Rescued: failover शामिल होता है।

# If primary bank API fails, try backup provider
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://bank-a.com/api/pay" \
  -H "X-Failover-URL: https://bank-b.com/api/pay" \
  -H "X-Retry-Count: 2" \
  -H "X-Proxy-Timeout: 5s" \
  -H "X-Attempt-Timeout: 1.5s" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "usd"}'

# AI provider failover
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.openai.com/v1/chat/completions" \
  -H "X-Identity-Key: Bearer $OPENAI_KEY" \
  -H "X-Failover-URL: https://api.anthropic.com/v1/messages" \
  -H "X-Proxy-Timeout: 10s" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [...]}'

---

इडेम्पोटेंसी (Idempotency)

X-Proxy-Idempotency-Key

अनुरोधों को डुप्लिकेट होने से रोकने के लिए कस्टम इडेम्पोटेंसी कुंजी। गेटवे इस कुंजी को 60-सेकंड TTL के साथ SETNX का उपयोग करके Redis में संग्रहीत करता है। यदि वही कुंजी किसी इन-फ़्लाइट अनुरोध के दौरान आती है, तो डुप्लिकेट पूर्ण होने तक प्रतीक्षा करता है और वही प्रतिक्रिया प्राप्त करता है। यदि अनुरोध पहले से पूर्ण है, तो कैश की गई प्रतिक्रिया तुरंत लौटाई जाती है।

यदि यह हेडर प्रदान नहीं किया जाता, तो गेटवे स्वतः SHA256(ClientID + TargetURL + Method + Body) से कुंजी की गणना करता है।

# Explicit idempotency key — prevent duplicate payment charges
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-Proxy-Idempotency-Key: order_789_charge_attempt_1" \
  -H "X-Retry-Count: 3" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'
# If retried within 60s with the same key, returns the original response — no duplicate charge

# Idempotency with webhook callback
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-Proxy-Idempotency-Key: txn_abc123" \
  -H "X-Webhook-Callback: https://your-app.com/webhook" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd"}'
# Returns 202 Accepted with job_id
# If retried with same key → returns same 202 with same job_id (no duplicate job queued)

---

एसिंक्रोनस प्रोसेसिंग (Asynchronous Processing)

X-Webhook-Callback

एसिंक्रोनस मोड सक्षम करता है। गेटवे तुरंत 202 Accepted और एक job_id लौटाता है, अनुरोध को Redis-backed वर्कर क्यू में धकेलता है, और अपस्ट्रीम के प्रतिक्रिया देने पर परिणाम आपके कॉलबैक URL पर POST करता है।

वर्कर पूर्ण रिट्राय लॉजिक का समर्थन करता है और यदि अपस्ट्रीम अस्थायी रूप से अनुपलब्ध है तो घंटों तक रिट्राय कर सकता है।

जॉब्स को प्लान-विशिष्ट क्यू (business, developer, free) में भेजे जाते हैं और भुगतान करने वाले ग्राहकों के जॉब को मुफ़्त-स्तरीय जॉब से ब्लॉक होने से रोकने के लिए weighted प्रोसेसिंग प्राथमिकता दी जाती है।

# Basic async payment processing
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-Webhook-Callback: https://your-app.com/api/webhooks/payments" \
  -H "X-Proxy-Idempotency-Key: order_789_pay_1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'

# Response:
# HTTP/1.1 202 Accepted
# {"status": "Accepted", "job_id": "8fd2a023-df21-4ea7-8b01-5d9f0f9b36ea"}

# Async with cascade route and retries
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: payment-cascade" \
  -H "X-Webhook-Callback: https://your-app.com/results" \
  -H "X-Retry-Count: 3" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "usd"}'

जॉब पूर्ण होने पर आपका कॉलबैक एंडपॉइंट अपस्ट्रीम रिस्पॉन्स बॉडी के साथ एक POST प्राप्त करता है।

---

रिस्पॉन्स ट्रांसफ़ॉर्मेशन (Response Transformation)

X-Extract-Redirect

JSONPath का उपयोग करके अपस्ट्रीम रिस्पॉन्स बॉडी से एक URL निकालता है और उस URL पर 302 Found रीडायरेक्ट लौटाता है।

• यह कैसे काम करता है: सफल 2xx प्रतिक्रिया पर, प्रॉक्सी निर्दिष्ट JSONPath के लिए रिस्पॉन्स बॉडी खोजता है। यदि मिलता है, तो क्लाइंट को Location के रूप में उस URL के साथ 302 Found रीडायरेक्ट लौटाता है।
• फ़ॉलबैक चेन: एकाधिक पथ आज़माने के लिए लॉजिकल OR (||) का समर्थन करता है (जैसे, $.url || $.checkoutUrl)।
• टाइप कास्टिंग: गैर-string मानों (संख्याओं/booleans) को स्वतः string में बदलता है।
• केवल 2xx: यदि अपस्ट्रीम non-2xx एरर कोड (जैसे, 400 या 500) लौटाता है तो निष्पादित नहीं होता।

# Extract payment redirect URL from response
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.payment-provider.com/create-session" \
  -H "X-Extract-Redirect: $.url || $.checkoutUrl || $.data.payment_link" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd"}'
# If upstream returns {"url": "https://checkout.stripe.com/c/pay/cs_..."} →
# Gateway returns: 302 Found, Location: https://checkout.stripe.com/c/pay/cs_...

# Extract from 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" \
  -H "Content-Type: application/json" \
  -d '{"amount": {"currency": "EUR", "value": 1000}}'

X-Extract-Map

JSONPath का उपयोग करके अपस्ट्रीम रिस्पॉन्स बॉडी से फ़ील्ड निकालता और नाम बदलता है। पूर्ण अपस्ट्रीम प्रतिक्रिया के बजाय एक रूपांतरित JSON ऑब्जेक्ट लौटाता है।

• एकाधिक मैपिंग: कॉमा से अलग करके एक साथ कई फ़ील्ड निकालें/नाम बदलें ($.id=>charge_id, $.status=>state)।
• नेस्टेड संरचनाएँ: टारगेट key (targetKey) नेस्टेड JSON उत्पन्न करने के लिए dot-notation का समर्थन करता है (जैसे $.id=>data.charge.id → {"data":{"charge":{"id":"..."}}})।
• Arrays: खाली ब्रैकेट [] का उपयोग करके ऑब्जेक्ट की पूरी arrays को बदलें (जैसे orders[].id=>data.orders[].order_id)।
• वैल्यू टेम्पलेट: पैरेंथेसिस में फ़ॉर्मेटिंग टेम्पलेट जोड़ें (जैसे $.order_id=>order_text(Order #{value}) या sibling फ़ील्ड: status=>status_text(Order {order_id} is {value}))।
• सिंगल फ़ील्ड फ़ॉलबैक: यदि कोई टारगेट key निर्दिष्ट नहीं है, तो निकाला गया मान extracted key के अंतर्गत लौटाया जाता है (जैसे, $.status → {"extracted": "success"})।

# Extract a single field
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"}

# Map multiple fields to custom keys
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_charged" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'
# Returns: {"charge_id": "ch_3Pz9...", "payment_status": "succeeded", "amount_charged": 2000}

# Normalize different API responses to your schema
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://legacy-crm.internal/api/users/42" \
  -H "X-Extract-Map: $.user_identifier=>id, $.full_name=>name, $.email_address=>email"
# Upstream returns: {"user_identifier": "u_42", "full_name": "John", "email_address": "[email protected]"}
# MirApi returns:   {"id": "u_42", "name": "John", "email": "[email protected]"}

---

रिस्पॉन्स हेडर (Response Header)

जब कोई अनुरोध बचाया (rescue) जाता है तो MirApi प्रतिक्रियाओं में एक हेडर जोड़ता है:

हेडर	मान	विवरण
X-Rescued	retry	एक या अधिक स्वचालित रिट्राय के बाद सफलतापूर्वक प्रतिक्रिया परोसी गई
X-Rescued	cache	अपस्ट्रीम विफलता के बाद स्मार्ट कैश से प्रतिक्रिया परोसी गई
X-Rescued	failover	प्राथमिक विफलता के बाद X-Failover-URL से प्रतिक्रिया परोसी गई
X-Rescued	cascade_fallback	रूट में एक कम प्राथमिकता वाले कैस्केड टारगेट से प्रतिक्रिया परोसी गई

यदि कोई अनुरोध पहले प्रयास में बिना किसी rescue के सफल होता है, तो X-Rescued प्रतिक्रिया में नहीं जोड़ा जाता।