परिचय और आर्किटेक्चर

MirApi Gateway एक header-driven API proxy है जो आपके application और किसी भी third-party API के बीच स्थित होता है। अपने requests को https://proxy.mirapi.io/ पर point करके और HTTP headers जोड़कर, आपको automatic retries, smart caching, failover routing, zero-logging, PCI-DSS protection, और बहुत कुछ मिलता है — बिना आपके integration logic में कोई code बदलाव किए।

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

Your App -> MirApi Gateway -> Upstream API(s)
              |
         Auth Check (X-MirApi-Key)
         PCI-DSS Guard (Luhn Scan)
         Idempotency Lock (Redis SETNX)
         Resilience Engine (Retry / Circuit Breaker / Cache / Failover)
         Header Stripping (X-* headers hidden from upstream)

Gateway हर request को intercept करता है, आपकी API key को verify करता है, card data के लिए scan करता है, reliability rules लागू करता है, और upstream API को request forward करता है — जिसमें सभी internal proxy headers हटा दिए जाते हैं।

आर्किटेक्चर का अवलोकन

Request Lifecycle

हर inbound request इस fixed pipeline से क्रमबद्ध रूप से गुज़रती है:

1. Authentication — X-MirApi-Key header को Redis cache (SHA-256 hash lookup) के विरुद्ध verify किया जाता है। यदि header अनुपस्थित या अमान्य है, तो request तुरंत 401 Unauthorized के साथ अस्वीकार कर दी जाती है।

2. PCI-DSS Guard — Raw request body को 13–16 अंकों के उन sequences के लिए scan किया जाता है जो Luhn algorithm पास करते हैं। यदि कोई raw card number मिलता है, तो request 400 Bad Request के साथ block हो जाती है। Body को कभी भी logs में नहीं लिखा जाता।

3. Idempotency Check — X-Proxy-Idempotency-Key header पढ़ा जाता है। यदि अनुपस्थित हो, तो gateway SHA256(ClientID + TargetURL + Method + Body) का उपयोग करके स्वयं एक key compute करता है। Key को SETNX के माध्यम से Redis में 60 सेकंड के लिए lock किया जाता है। Concurrent duplicate requests पहली request के पूरी होने तक प्रतीक्षा करती हैं और फिर memory से वही response प्राप्त करती हैं।

4. Routing Decision — Gateway X-Route-Key (database-backed cascade route) या X-Target-URL (direct proxy) की जाँच करता है। यदि दोनों में से कोई भी मौजूद नहीं है, तो request 400 Bad Request के साथ अस्वीकार कर दी जाती है।

5. Async Check — यदि X-Webhook-Callback मौजूद है, तो job को Redis queue में push कर दिया जाता है और तुरंत 202 Accepted return किया जाता है। Background worker पूर्ण retry logic के साथ execution संभालता है।

6. Resilience Pipeline — Synchronous requests के लिए:

   • Circuit Breaker (X-Circuit-Breaker: on): यदि target host के लिए circuit OPEN है, तो request block हो जाती है — जब तक कि Smart Cache entry मौजूद न हो।
   • Retry Loop (X-Retry-Count): Failed requests को exponential backoff + jitter के साथ retry किया जाता है (प्रति delay अधिकतम 10 सेकंड)।
   • Failover URL (X-Failover-URL): यदि सभी retries fail हो जाएं, तो request fallback endpoint पर forward की जाती है।
   • Smart Cache (X-Smart-Cache): यदि upstream अभी भी fail हो रहा हो, तो last cached successful response return किया जाता है। Response में X-Rescued: cache शामिल होता है।

7. Header Stripping — Upstream API को forward करने से पहले, सभी X-Target-*, X-Retry-*, X-MirApi-*, X-Proxy-*, X-Smart-*, X-Failover-*, X-Identity-*, X-Webhook-*, X-Extract-*, और अन्य internal headers हटा दिए जाते हैं। Upstream को proxy orchestration headers कभी नहीं दिखते।

8. Secret Injection — यदि X-Identity-Key set है, तो उसका मान outbound Authorization header में inject किया जाता है। यदि X-Proxy-Master-Key set है, तो gateway database से matching credential decrypt करके उसे Authorization के रूप में inject करता है (या cascade routing targets के लिए target-specific credentials decrypt करके custom headers/templates लागू करता है)।

9. Response — Upstream response (headers + body) आपके app को यथावत् return किया जाता है। यदि request को retry, cache, failover, या cascade routing द्वारा rescue किया गया था, तो X-Rescued: <reason> header जोड़ा जाता है।

Response Header

जब किसी fallback mechanism द्वारा request rescue की जाती है, तो MirApi एक response header जोड़ता है:

Header	Values	Description
X-Rescued	retry, cache, failover, cascade_fallback	बताता है कि request किस प्रकार save की गई। केवल तभी मौजूद होता है जब rescue हुआ हो।

नोट: MirApi हर response में latency, attempt number, या origin headers नहीं जोड़ता। सभी metrics (requests, rescued requests, rescued capital) internally record किए जाते हैं और dashboard में देखे जा सकते हैं।

समर्थित Use Cases

MirApi Gateway किसी भी HTTP API के साथ काम करता है। सामान्य integrations में शामिल हैं:

• Payment processors: Stripe, PayPal, Adyen — idempotency के बिना charges को retry होने से बचाएं
• AI/ML providers: OpenAI, Anthropic, Groq — rate-limit होने पर providers के बीच cascade करें
• Communication: Twilio, SendGrid — retry loops के साथ message delivery सुनिश्चित करें
• Banking/Finance: Plaid, Open Banking APIs — exchange rates और catalog data के लिए Smart Cache
• कोई भी REST API: बस X-Target-URL set करें और आवश्यक reliability headers जोड़ें

अगले कदम

-> अपना पहला resilient request बनाने के लिए Quickstart Guide का अनुसरण करें।