Стиснення і кешування

Великі публічні запити на читання, як-от GET /markets, повертають мегабайти JSON. Запитуйте стиснення, а про свіжість кожної відповіді вам скаже заголовок Cache-Control.

Стиснення

Надішліть Accept-Encoding: gzip, і API поверне тіло, стиснене gzip, із заголовком Content-Encoding: gzip. Розмір GET /markets зменшується приблизно з 4 МБ до приблизно 0,6 МБ.

• Браузери і fetch у Node.js надсилають цей заголовок і розпаковують відповідь автоматично.
• Rust hypercall-client вмикає gzip у своєму HTTP-клієнті, тому кожен REST-виклик запитує стиснення і прозоро його декодує.
• Python requests і httpx за замовчуванням надсилають заголовок і розпаковують відповідь. Звичайний urllib не робить ні того, ні іншого, тому ви отримуєте нестиснене тіло.
• curl потребує --compressed.

Відповіді розміром менше приблизно 1 КБ надсилаються без стиснення. Це не стосується фреймів WebSocket; див. стиснення WebSocket.

Cache-Control

Кожна відповідь на читання повідомляє, чи може спільний кеш її зберігати.

Заголовок відповіді	Де ви його бачите	Що він означає
public, max-age=N	Публічні ринкові дані: /markets, /instruments, /instrument-specs, /exchange-info, греки, зведення за опціонами та експіраціями, історичні теоретичні ціни, читання пулів, /version	Будь-який кеш може повторно використовувати тіло до N секунд. Здебільшого це від 1 до 15 секунд; для історичних даних цей час може бути довшим.
public, max-age=N, stale-while-revalidate=M	Деякі з наведених вище запитів	Після N секунд кеш може ще до M секунд віддавати старе тіло, поки у фоновому режимі отримує свіже.
no-store	Запити, прив'язані до гаманця, і автентифіковані запити: портфель, відкриті ордери, виконання, угоди з фільтром за гаманцем, конфігурація MMP тощо	Жоден кеш їх не зберігає. Кожен запит доходить до API.
немає	Усе інше, зокрема /orderbook і всі запити на запис	Не кешується.

Вважайте, що дані з public-запиту можуть бути застарілими на max-age секунд (плюс stale-while-revalidate, якщо він є). Коли вам потрібен найактуальніший стан для торгового рішення, отримуйте його з каналів WebSocket або із запиту, прив'язаного до гаманця, які ніколи не кешуються.

Відповіді з помилками (4xx, 5xx) ніколи не містять public і ніколи не кешуються. Кеш не продовжує віддавати прострочене тіло, поки API повертає помилки; ви отримуєте помилку.

Запити, які завжди доходять до API

Кешоване тіло ніколи не повертається на запит, що містить будь-що з наведеного нижче, і ніщо з отриманого таким запитом не зберігається:

• Authorization або Cookie
• X-Hypercall-Signature або X-Hypercall-Expires-At-Ms (підписані запити на читання, як-от конфігурація MMP)
• X-Hypercall-Fence або X-Hypercall-Fence-Wait (узгодженість читання після запису, див. Захист маркетмейкера)
• X-Hypercall-Gateway-Token або X-Admin-Key
• будь-який метод, окрім GET або HEAD, а також оновлення з'єднання до WebSocket

Бар'єри читання після запису і кешування ніколи не поєднуються. Маршрут, який враховує X-Hypercall-Fence, має no-store, а public-маршрут ніколи не чекає на бар'єр.

X-Cache-Status

Відповіді, що проходять через edge-кеш Hypercall, містять заголовок X-Cache-Status:

Значення	Що означає
HIT	Віддано з edge-кешу в межах max-age.
MISS	Отримано від API. Якщо відповідь була public, тепер вона кешована.
BYPASS	Запит містив заголовок зі списку вище, тому пішов безпосередньо до API, і нічого не збережено.
EXPIRED	Термін дії кешованої копії минув, тому API запитано повторно.
STALE або UPDATING	Віддано з кешу в межах вікна stale-while-revalidate, поки отримується свіжа копія.

Запити на запис та інші запити, відмінні від GET, не мають X-Cache-Status. Заголовок має лише інформаційний характер: не будуйте на ньому торгову логіку. Edge-кеш поки є не в усіх середовищах. Відповідь без цього заголовка надійшла безпосередньо від API.