ETag et If-None-Match
ETag est un en-tête de réponse HTTP qui porte une étiquette de version des données : tant que la ressource reste identique, l’étiquette l’est aussi. Le client renvoie l’étiquette dans l’en-tête If-None-Match et, si le serveur a toujours cette version, il répond 304 Not Modified sans corps. Les deux en-têtes sont définis dans la RFC 9110 (HTTP Semantics, 2022).
Comment fonctionne une requête conditionnelle
Un échange hypothétique avec l’étiquette "a7f3c9" :
| Étape | Requête | Réponse |
|---|---|---|
| 1 | GET /v1/funding/rates | 200, ETag: "a7f3c9", corps JSON |
| 2 | Même URL avec If-None-Match: "a7f3c9" | 304 Not Modified, sans corps |
| 3 | Même requête après la mise à jour des données | 200, une nouvelle étiquette et un nouveau JSON |
Selon le standard, une réponse 304 s’arrête après ses en-têtes et ne peut pas avoir de corps : le client réutilise donc sa propre copie. Le serveur compare les étiquettes ; le client se contente de garder la dernière étiquette reçue et de l’envoyer avec la même requête.
import os
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/rates"
cache = {"tag": None, "data": None} # l’ensemble complet et son étiquette
def get_rates():
headers = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
if cache["tag"]:
headers["If-None-Match"] = cache["tag"]
r = requests.get(URL, headers=headers, timeout=10)
if r.status_code == 304:
return cache["data"] # données inchangées, aucun quota consommé
r.raise_for_status()
cache["tag"] = r.headers.get("ETag")
cache["data"] = r.json()["data"]
return cache["data"]
# choisir le coin en local : une requête avec coin arrive sans ETag
btc = [row for row in get_rates() if row["coin"] == "BTC"]
ETag dans Genesis API
Dans Genesis API, seule une réponse 200 compte comme un appel : un 304 ne consomme pas votre quota, mais il compte dans la limite de requêtes par seconde. Il n’a pas de corps, et les réponses de moins de 64 Ko ne comptent pas dans la limite de volume de téléchargement. Les jeux de données complets sans filtres portent l’étiquette : la réponse à une requête avec coin ou des filtres est construite pour cette requête et arrive sans ETag ; là, c’est le filtre lui-même qui économise le trafic (plans et limites).
Exemple hypothétique : un bot télécharge toutes les 60 secondes le résumé complet de l’analytique de funding /funding/analytics/summary (plans Pro et Max). La section pèse environ 600 Ko compressée en gzip et son étiquette change à peu près toutes les 15 minutes. Sur 30 jours, cela fait 30 × 24 × 60 = 43 200 requêtes. Avec If-None-Match, seules 30 × 24 × 4 = 2 880 téléchargent la section complète ; les 40 320 autres reviennent en 304, sans corps ni quota consommé. Le trafic passe d’environ 26 Go à 1,7 Go.
Voir aussi : API polling, HTTP 429, fraîcheur des données, format de réponse, ETag et erreurs de Genesis API, comment interroger une API sans atteindre les limites.
Questions et réponses
Une réponse 304 consomme-t-elle le quota de Genesis API ?
Non. Seules les réponses 200 consomment le quota ; 304 et les erreurs sont gratuites, mais comptent dans la limite de requêtes par seconde.
Que faire si la réponse n’a pas d’ETag ?
Interrogez l’API au plus aussi souvent que meta.freshness_sec et comparez meta.updated_at avec la réponse précédente : une valeur identique signifie que l’instantané n’a pas été mis à jour.