Compression et mise en cache

Les grandes lectures publiques comme GET /markets représentent plusieurs mégaoctets de JSON. Demandez la compression, et laissez l'en-tête Cache-Control de chaque réponse vous indiquer sa fraîcheur.

Compression

Envoyez Accept-Encoding: gzip et l'API renvoie le corps compressé en gzip avec Content-Encoding: gzip. GET /markets passe d'environ 4 Mo à environ 0,6 Mo.

• Les navigateurs et fetch de Node.js envoient l'en-tête et décompressent automatiquement.
• Rust hypercall-client active gzip dans son client HTTP, de sorte que chaque appel REST le demande et le décode de manière transparente.
• Python : requests et httpx envoient l'en-tête et décompressent par défaut. urllib seul ne fait ni l'un ni l'autre, vous recevez donc le corps non compressé.
• curl nécessite --compressed.

Les réponses de moins d'environ 1 Ko sont envoyées sans compression. Les trames WebSocket ne sont pas concernées ; voir Compression WebSocket.

Cache-Control

Chaque lecture vous indique si un cache partagé peut la conserver.

En-tête de réponse	Où vous le voyez	Signification
public, max-age=N	Données de marché publiques : /markets, /instruments, /instrument-specs, /exchange-info, grecques, résumés d'options et d'échéances, théos historiques, lectures de pools, /version	N'importe quel cache peut réutiliser le corps pendant au plus N secondes. La plupart vont de 1 à 15 secondes ; les données historiques peuvent durer plus longtemps.
public, max-age=N, stale-while-revalidate=M	Certaines des lectures ci-dessus	Après N secondes, un cache peut continuer à servir l'ancien corps pendant au plus M secondes supplémentaires, le temps d'en récupérer un nouveau en arrière-plan.
no-store	Lectures propres à un portefeuille et lectures authentifiées : portefeuille de positions, ordres ouverts, exécutions, transactions filtrées par portefeuille, configuration MMP, et autres lectures similaires	Jamais stockées par aucun cache. Chaque requête atteint l'API.
aucun	Tout le reste, y compris /orderbook et toutes les écritures	Non mis en cache.

Considérez qu'une lecture public peut dater de max-age secondes au plus (plus l'éventuel stale-while-revalidate). Lorsque vous avez besoin de l'état le plus récent pour une décision de trading, lisez-le depuis les canaux WebSocket ou depuis une lecture propre à un portefeuille, qui ne sont jamais mis en cache.

Les réponses d'erreur (4xx, 5xx) ne portent jamais public et ne sont jamais mises en cache. Un cache ne continue pas à servir un corps expiré pendant que l'API renvoie des erreurs ; vous recevez l'erreur.

Requêtes qui atteignent toujours l'API

Un corps mis en cache n'est jamais renvoyé à une requête qui porte l'un des éléments suivants, et rien de ce que reçoit une telle requête n'est stocké :

• Authorization ou Cookie
• X-Hypercall-Signature ou X-Hypercall-Expires-At-Ms (lectures signées comme la configuration MMP)
• X-Hypercall-Fence ou X-Hypercall-Fence-Wait (cohérence lecture après écriture, voir Market Maker Protection)
• X-Hypercall-Gateway-Token ou X-Admin-Key
• toute méthode autre que GET ou HEAD, ainsi que les upgrades WebSocket

Les barrières de lecture après écriture et la mise en cache ne se combinent jamais. Une route qui honore X-Hypercall-Fence est no-store, et une route public n'attend jamais une barrière.

X-Cache-Status

Les réponses qui transitent par le cache edge de Hypercall portent X-Cache-Status :

Valeur	Signification
HIT	Servie depuis le cache edge, dans la limite de max-age.
MISS	Récupérée depuis l'API. Si la réponse était public, elle est désormais en cache.
BYPASS	La requête portait un en-tête de la liste ci-dessus ; elle est donc allée directement à l'API et rien n'a été stocké.
EXPIRED	La copie en cache avait dépassé sa durée de vie ; l'API a donc été interrogée à nouveau.
STALE ou UPDATING	Servie depuis le cache dans la fenêtre stale-while-revalidate pendant qu'une copie fraîche est récupérée.

Les écritures et les autres requêtes non-GET n'ont pas de X-Cache-Status. L'en-tête est informatif : ne faites pas dépendre votre logique de trading de sa valeur. Tous les environnements ne disposent pas encore du cache edge. Une réponse sans cet en-tête provient directement de l'API.