स्मार्ट कैश फ़ॉलबैक

MirApi का Smart Cache, Redis में सफल upstream रिस्पॉन्स को संग्रहीत करता है और जब upstream अनुपलब्ध हो, rate-limited हो, या error लौटाए तो उन्हें आपातकालीन फ़ॉलबैक के रूप में सर्व करता है। यह एक विफलता बचाव तंत्र है — सामान्य उद्देश्य का कैश नहीं। हर अनुरोध हमेशा पहले upstream को आज़माता है; कैश्ड डेटा केवल तभी लौटाया जाता है जब सभी प्रयास विफल हो जाएं।

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

1. पहला सफल अनुरोध: MirApi upstream को अग्रेषित करता है और, सफलता पर, रिस्पॉन्स बॉडी को कॉन्फ़िगर किए गए TTL के साथ Redis में कैश करता है।
2. बाद के अनुरोध: अनुरोध को सामान्य रूप से upstream को अग्रेषित किया जाता है। सफलता पर कैश नहीं सर्व किया जाता — केवल विफलता पर।
3. Upstream विफलता (सभी retries समाप्त): MirApi एक कैश एंट्री खोजता है। मिलने पर, X-Rescued: cache के साथ कैश्ड रिस्पॉन्स लौटाया जाता है। कैश एंट्री न मिलने पर, upstream की error लौटाई जाती है।

Cache key इससे गणना की जाती है: SHA256(ClientID + TargetURL + Method + RequestBody) — इसलिए अलग-अलग request bodies (जैसे, अलग currency मान) अलग-अलग cache entries उत्पन्न करती हैं।

Smart Cache सक्षम करें

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"

Header:

Header	उदाहरण मान	विवरण
X-Smart-Cache	60s, 5m, 1h	सफल रिस्पॉन्स के लिए Cache TTL। Go durations स्वीकार करता है।

उपयोग के मामले

1. Exchange Rate API (सबसे सामान्य)

Exchange rates को कैश करें ताकि rates API बंद होने पर भी आपका ऐप काम करता रहे:

# GET current exchange rates - cached for 5 minutes
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.exchangerate.host/latest?base=USD" \
  -H "X-Smart-Cache: 300s"

# If the API returns 503 (cached data found):
# HTTP/1.1 200 OK
# X-Rescued: cache
# {"base": "USD", "rates": {"EUR": 0.9234, ...}}

2. Product Catalog / Configuration Data

धीमे backends से कम बदलने वाले डेटा को कैश करें:

curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.yourstore.com/v1/products?category=electronics" \
  -H "X-Smart-Cache: 10m" \
  -H "X-Retry-Count: 2"
# Cached for 10 minutes per unique URL+body combination

3. AI Embeddings (महंगे + धीमे)

लागत और समय बचाने के लिए समान inputs के लिए embeddings को कैश करें:

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 "Content-Type: application/json" \
  -d '{"input": "The quick brown fox", "model": "text-embedding-3-small"}'
# Same input -> same SHA256 body hash -> same cache key
# If OpenAI is down: serves cached embedding from Redis

4. Smart Cache + Circuit Breaker

जब circuit खुलता है, तो cache तुरंत सर्व होता है — upstream पर कोई कॉल नहीं की जाती:

curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.exchangerate.host/latest" \
  -H "X-Circuit-Breaker: on" \
  -H "X-Smart-Cache: 600s" \
  -H "X-Retry-Count: 2"
# Normal: upstream -> cache stored in Redis
# Circuit OPEN: no upstream call -> cache served immediately -> X-Rescued: cache

5. Smart Cache + Retry

Cache केवल सभी retries समाप्त होने के बाद ही देखा जाता है:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.bankapi.com/rates" \
  -H "X-Smart-Cache: 1h" \
  -H "X-Retry-Count: 3" \
  -H "X-Retry-Delay: 500ms"
# Attempt 1 -> 503
# Attempt 2 -> 503 (after 500ms)
# Attempt 3 -> 503 (after 1s)
# Attempt 4 -> 503 (after 2s)
# All failed -> check Redis -> cache HIT -> serve stale -> X-Rescued: cache

Cache रिस्पॉन्स संकेतक

जब कैश्ड रिस्पॉन्स सर्व किया जाता है, तो X-Rescued: cache header जोड़ा जाता है:

HTTP/1.1 200 OK
X-Rescued: cache
Content-Type: application/json

{"base": "USD", "rates": {"EUR": 0.9234, ...}}

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

Request Method के अनुसार Cache व्यवहार

Method	कैश होता है?	नोट्स
GET	हाँ	पूरी body कैश होती है
POST	हाँ	Body hash को cache key में शामिल किया जाता है — समान body = समान cache entry
PUT / PATCH	हाँ	POST जैसा ही body hash तर्क
DELETE	सावधानी से उपयोग करें	समान तर्क, लेकिन DELETE responses को दोबारा सर्व करना उचित नहीं हो सकता

सर्वोत्तम अभ्यास

• Read-heavy endpoints के लिए हमेशा Smart Cache का उपयोग करें जैसे exchange rates, product catalogs, और configuration APIs — ये APIs बंद हो सकती हैं, और कैश्ड डेटा error से लगभग हमेशा बेहतर होता है।
• X-Circuit-Breaker: on के साथ मिलाएं critical APIs के लिए, ताकि upstream विफल होते ही उसे बार-बार hit करना बंद हो जाए।
• उचित TTLs का उपयोग करें: exchange rates → 60s-300s; product catalogs → 5m-30m; embeddings → 1h-24h।
• Write operations के लिए (payments, mutations), Smart Cache अंतिम उपाय के रूप में काम करता है। Stale cached responses की double-processing से बचने के लिए X-Proxy-Idempotency-Key के साथ idempotency सुनिश्चित करें।