Довідник заголовків

Повний довідник усіх X-* контрольних заголовків, що підтримуються MirApi Gateway. Ці заголовки зчитуються шлюзом на кожному запиті та видаляються перед пересиланням до upstream API — upstream їх ніколи не бачить.

---

Автентифікація

X-MirApi-Key

Обов’язковий у кожному запиті.

Ваш API-ключ MirApi. Шлюз перевіряє його через кеш Redis за SHA-256 хешем. Повертає 401 Unauthorized якщо відсутній або недійсний.

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

---

Маршрутизація

X-Target-URL

Обов’язковий (якщо не використовується X-Route-Key).

Повна URL upstream API-ендпоінту для пересилання запиту. Шлюз валідує URL і блокує кругові посилання на самого себе.

# GET-проксі
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges"

# POST з тілом
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": "Привіт"}]}'

X-Route-Key

Використовує попередньо налаштований маршрут з дашборду замість X-Target-URL. Маршрут зберігає цільові URL, стратегію каскаду, тайм-аут, маппінг тіла та правила витягнення відповіді.

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"}'

---

Розвантаження секретів

X-Identity-Key

Пересилається як заголовок Authorization до upstream. Зчитується в пам’ять на час запиту, ніколи не записується в логи або постійне сховище.

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_xxxx" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'
# Stripe отримує: Authorization: Bearer sk_live_xxxx
# Ваші логи: нічого про вміст ключа

X-Proxy-Master-Key

Парольна фраза дешифрування для облікових даних, що зберігаються зашифрованими в БД. Шлюз розшифровує відповідні облікові дані та ін’єктує як Authorization.

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"}'

X-Credential-ID

UUID конкретного запису облікових даних для використання з X-Proxy-Master-Key. Якщо не вказаний — шлюз підбирає облікові дані за підрядком цільового хостнейму.

---

Надійність

X-Proxy-Timeout

Максимальний час очікування відповіді від upstream на одну спробу. Приймає Go duration рядки: 500ms, 1s, 5s, 30s. За замовчуванням: 30s. Максимальне значення, яке може бути встановлено — 30s.

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-Retry-Count: 3"

X-Retry-Count

Кількість додаткових повторних спроб при збої (статус 5xx або помилка з’єднання). За замовчуванням: 0.

X-Retry-Delay

Базова затримка між повторами. Шлюз використовує exponential backoff з jitter: base_delay × 2^attempt + random_jitter (до 50%), з обмеженням 10 секунд. Приймає Go duration рядки: 100ms, 500ms, 1s.

# 3 повтори, починаючи з 200ms
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" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'

X-Circuit-Breaker

Вмикає circuit breaker для цільового хоста. Значення: on або true. Після 5 послідовних збоїв за 1 хвилину контур відкривається на 15 секунд.

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"}'

X-Smart-Cache

Кешує останню успішну відповідь upstream у Redis. При збої (після всіх повторів) кешована відповідь повертається замість помилки. Приймає Go duration рядки: 60s, 5m, 1h.

Ключ кешу: SHA256(ClientID + TargetURL + Method + RequestBody).

# Кешувати курси валют на 5 хвилин
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"
# При збої upstream → X-Rescued: cache

X-Failover-URL

Резервний upstream URL, якщо первинний (X-Target-URL) провалився після всіх повторів.

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://primary-bank.com/pay" \
  -H "X-Failover-URL: https://backup-bank.com/pay" \
  -H "X-Retry-Count: 2"
# При збої primary → X-Rescued: failover

---

Idempotency

X-Proxy-Idempotency-Key

Власний ключ idempotency для дедублікації запитів. Зберігається в Redis з TTL 60 секунд через SETNX. Дублікати чекають завершення першого запиту і отримують ту саму відповідь.

Якщо не вказаний — автоматично обчислюється з SHA256(ClientID + TargetURL + Method + Body).

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: order_789_charge_attempt_1" \
  -H "X-Retry-Count: 3" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'
# Повтор з тим самим ключем → оригінальна відповідь, без дублікату списання

---

Асинхронна обробка

X-Webhook-Callback

Вмикає асинхронний режим. Шлюз повертає 202 Accepted з job_id, поміщає завдання в чергу Redis та надсилає результат POST-запитом на вашу callback URL.

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" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'
# → 202: {"status": "Accepted", "job_id": "8fd2a023-..."}

---

Трансформація відповіді

X-Extract-Redirect

Витягує URL з тіла відповіді upstream через JSONPath і повертає 302 Found редирект.

• Як це працює: При успішній відповіді від upstream (статус-код 2xx) проксі аналізує тіло відповіді, шукаючи значення за вказаним JSONPath. Якщо значення знайдено, проксі перериває передачу оригінальної відповіді та повертає HTTP-редирект 302 Found на отриманий URL.
• Підтримка ланцюжків альтернатив (fallback): Підтримує логічне або || (наприклад, $.url || $.checkoutUrl).
• Автоматичне приведення типів: Якщо значення не є рядком (число чи логічне значення), воно конвертується у рядок автоматично.
• Тільки для 2xx: Якщо upstream повертає помилку (наприклад 400 або 500), редирект не виконується, щоб клієнт отримав оригінальну помилку.

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.payment.com/sessions" \
  -H "X-Extract-Redirect: $.url || $.checkoutUrl || $.data.payment_link"
# → 302 Found, Location: https://checkout.stripe.com/...

X-Extract-Map

Витягує та перейменовує поля з тіла відповіді upstream. Повертає новий JSON-об’єкт тільки з вибраними полями.

• Множинний мапінг через кому: Перейменування кількох полів одночасно ($.id=>charge_id, $.status=>state).
• Створення вкладених структур: Ключ цілі (targetKey) підтримує крапкову нотацію для генерації вкладених об’єктів JSON (наприклад, $.id=>data.charge.id згенерує {"data": {"charge": {"id": "..."}}}).
• Робота з масивами/списками: Трансформація масивів об’єктів за допомогою порожніх дужок [] (наприклад, provider_data.orders[].order_id=>data.orders[].order).
• Шаблонізація значень (Value Interpolation): Форматування значень за допомогою синтаксису target_key(Шаблон {value}), а також підстановка сусідніх полів з контексту (наприклад, status=>status_text(Order {order_id} is {value})).
• Single Field Fallback (без =>): Якщо передати просто JSONPath без вказівки цільового імені (наприклад, $.status), то значення буде повернуто у ключі extracted (наприклад, {"extracted": "success"}).

# Одне поле
curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://httpbin.org/get" \
  -H "X-Extract-Map: $.origin"
# → {"extracted": "93.123.45.67"}

# Кілька полів з перейменуванням
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-Extract-Map: $.id=>charge_id, $.status=>payment_status, $.amount=>amount_charged"
# → {"charge_id": "ch_3Pz9...", "payment_status": "succeeded", "amount_charged": 2000}

---

Заголовок відповіді

MirApi додає один заголовок до відповіді при рятуванні запиту:

Заголовок	Значення	Коли присутній
X-Rescued	retry	Відповідь успішно надано після одного або кількох автоматичних повторів
X-Rescued	cache	Відповідь зі Smart Cache після збою upstream
X-Rescued	failover	Відповідь з X-Failover-URL після збою primary
X-Rescued	cascade_fallback	Відповідь з нижчого пріоритету каскаду