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

Повний довідник усіх 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.

Для каскадної маршрутизації (X-Route-Key) цей ключ також використовується на рівні Edge для динамічного розшифрування унікальних облікових даних кожної окремої цілі (credential_id) перед надсиланням запиту до активної цілі.

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-Auth-Header

Опціонально (використовується разом з X-Proxy-Master-Key).

Визначає ім’я HTTP-заголовка, куди буде інжектовано розшифрований ключ. За замовчуванням: Authorization.

# Інжектувати розшифрований секрет у заголовок X-API-Key замість 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}}.

# Інжектувати розшифрований секрет за схемою Basic замість Bearer
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}}"

---

Надійність

X-Proxy-Timeout

Жорсткий ліміт на загальну тривалість HTTP-транзакції клієнта (включаючи всі спроби підключення та затримки експоненціального відкату). Якщо все виконання перевищує цей ліміт, шлюз перериває операцію та повертає статус 502 Bad Gateway (або 504 Gateway Timeout).

Приймає Go duration рядки: 500ms, 1s, 5s, 30s. За замовчуванням: 30s (обмежено максимум 30 секундами).

# Жорсткий 2-секундний загальний тайм-аут з 3 спробами повтору
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"

X-Attempt-Timeout

Ліміт тайм-ауту, який застосовується до кожної окремої спроби з’єднання з upstream-сервісом. Якщо окремий виклик перевищує цю межу, він вважається невдалим і запускає наступну спробу повтору (якщо налаштовано повторні спроби).

Приймає Go duration рядки (наприклад, 200ms, 1s, 5s). За замовчуванням: використовує значення X-Proxy-Timeout, якщо не вказано інше.

# Ліміт на окрему спробу в 1с, загальний ліміт часу на транзакцію 5с
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

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

# 3 повтори, починаючи з 200ms, з тайм-аутом спроби 1с та загальним лімітом 5с
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"}'

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" \
  -H "X-Proxy-Timeout: 5s" \
  -H "X-Attempt-Timeout: 1.5s"
# При збої 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	Відповідь з нижчого пріоритету каскаду