Вступ та Архітектура

MirApi Gateway — це заголовково-керований API-проксі, що розміщується між вашим додатком та будь-яким стороннім API. Вказавши запити на https://proxy.mirapi.io/ і додавши HTTP-заголовки, ви отримуєте автоматичні повтори, smart-кешування, каскадне перемикання, нульове логування, захист PCI-DSS тощо — без жодних змін у логіці інтеграції.

Як це працює

Ваш Додаток → MirApi Gateway → Upstream API(s)
                   ↕
              Перевірка Auth (X-MirApi-Key)
              PCI-DSS Guard (Luhn-сканування)
              Idempotency Lock (Redis SETNX)
              Resilience Engine (Retry / Circuit Breaker / Cache / Failover)
              Очищення заголовків (X-* прибираються перед upstream)

Шлюз перехоплює кожен запит, перевіряє ваш API-ключ, сканує на наявність даних карток, застосовує правила надійності та пересилає запит до upstream API з видаленими внутрішніми проксі-заголовками.

Огляд архітектури

Цикл запиту

Кожен вхідний запит проходить цей фіксований конвеєр по порядку:

1. Автентифікація — Перевіряється заголовок X-MirApi-Key через кеш Redis (пошук SHA-256 хешу). Якщо відсутній або недійсний — повертається 401 Unauthorized.

2. PCI-DSS Guard — Сирий текст тіла запиту сканується на послідовності 13–16 цифр, що проходять алгоритм Луна. Якщо виявлено сирий номер картки — запит блокується з 400 Bad Request. Тіло ніколи не записується в логи.

3. Перевірка Idempotency — Зчитується заголовок X-Proxy-Idempotency-Key. Якщо відсутній — шлюз автоматично обчислює ключ: SHA256(ClientID + TargetURL + Method + Body). Ключ блокується в Redis на 60 секунд через SETNX. Паралельні дублікати запитів чекають завершення першого, потім отримують ту саму відповідь.

4. Рішення маршрутизації — Шлюз перевіряє X-Route-Key (маршрут з бази даних) або X-Target-URL (прямий проксі). Якщо жоден не вказаний — повертається 400 Bad Request.

5. Перевірка Async — Якщо присутній X-Webhook-Callback, завдання поміщається у чергу Redis і повертається 202 Accepted. Фоновий воркер виконує операцію з повною логікою повторів.

6. Конвеєр надійності — Для синхронних запитів:

   • Circuit Breaker (X-Circuit-Breaker: on): Якщо контур OPEN для цільового хоста — запит блокується, якщо немає Smart Cache.
   • Retry Loop (X-Retry-Count): Невдалі запити повторюються з експоненціальним backoff + jitter (до 10 секунд на затримку).
   • Failover URL (X-Failover-URL): Якщо всі повтори провалились — запит пересилається на резервний ендпоінт.
   • Smart Cache (X-Smart-Cache): Якщо upstream все ще не відповідає — повертається остання кешована успішна відповідь з X-Rescued: cache.

7. Очищення заголовків — Перед пересиланням upstream всі X-Target-*, X-Retry-*, X-MirApi-*, X-Proxy-*, X-Smart-*, X-Failover-*, X-Identity-*, X-Webhook-*, X-Extract-* та інші внутрішні заголовки видаляються. Upstream ніколи не бачить проксі-заголовків.

8. Ін’єкція секретів — Якщо встановлено X-Identity-Key — його значення ін’єктується в заголовок Authorization. Якщо встановлено X-Proxy-Master-Key — шлюз розшифровує відповідні облікові дані з бази і ін’єктує як Authorization.

9. Відповідь — Відповідь upstream (заголовки + тіло) повертається вашому додатку як є. Якщо запит був врятований повтором, кешем, failover або каскадною маршрутизацією — додається заголовок X-Rescued: <reason>.

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

Коли запит врятовано одним із механізмів відмовостійкості, MirApi додає заголовок відповіді:

Заголовок	Значення	Опис
X-Rescued	retry, cache, failover, cascade_fallback	Вказує, як запит був врятований. Присутній лише при рятуванні.

Підтримувані випадки використання

MirApi Gateway працює з будь-яким HTTP API:

• Платіжні системи: Stripe, PayPal, Adyen — захист платежів від повторного виконання без idempotency
• AI/ML провайдери: OpenAI, Anthropic, Groq — каскад між провайдерами при rate-limiting
• Комунікація: Twilio, SendGrid — гарантована доставка повідомлень через retry
• Банківські API: Plaid, Open Banking — Smart Cache для курсів валют і каталогів

Наступні кроки

→ Дотримуйтесь Посібника швидкого старту, щоб зробити перший стійкий запит.