ETag и If-None-Match
ETag — заголовок ответа HTTP с меткой версии данных: пока ресурс не меняется, метка остаётся прежней. Клиент возвращает её в заголовке If-None-Match, и если версия на сервере та же, сервер отвечает 304 Not Modified без тела. Оба заголовка описаны в RFC 9110 (HTTP Semantics, 2022).
Как работает условный запрос
Условный пример с меткой "a7f3c9":
| Шаг | Запрос | Ответ |
|---|---|---|
| 1 | GET /v1/funding/rates | 200, ETag: "a7f3c9", JSON в теле |
| 2 | Тот же адрес и If-None-Match: "a7f3c9" | 304 Not Modified, тела нет |
| 3 | Тот же запрос после обновления данных | 200, новая метка и новый JSON |
По стандарту ответ 304 заканчивается заголовками и не может нести тело, поэтому клиент берёт данные из своей копии. Метки сравнивает сервер: клиенту достаточно хранить последнюю полученную и отправлять её в тот же запрос.
import os
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/rates"
cache = {"tag": None, "data": None} # полный набор и его метка
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"] # данные прежние, квота не списана
r.raise_for_status()
cache["tag"] = r.headers.get("ETag")
cache["data"] = r.json()["data"]
return cache["data"]
# монету выбираем у себя: запрос с coin приходит без ETag
btc = [row for row in get_rates() if row["coin"] == "BTC"]
ETag в Genesis API
Вызовом Genesis API считается только ответ 200: 304 квоту не тратит, но учитывается в лимите запросов в секунду. Тела у него нет, а ответы меньше 64 КБ в лимит объёма скачивания не входят. Метку получают полные наборы без фильтров: ответ на запрос с coin или фильтрами собирается под запрос и приходит без ETag, там трафик экономит сам фильтр (тарифы и лимиты).
Условный пример: бот раз в 60 секунд забирает полную сводку аналитики фандинга /funding/analytics/summary (тарифы Pro и Max). Секция весит около 600 КБ gzip, а её метка меняется примерно раз в 15 минут. За 30 дней это 30 × 24 × 60 = 43 200 запросов. С If-None-Match полную секцию скачают только 30 × 24 × 4 = 2 880 из них, остальные 40 320 придут ответом 304 без тела и без списания квоты. Трафик падает примерно с 26 ГБ до 1,7 ГБ.
Смотрите также: опрос API, ошибка 429, свежесть данных, формат ответа, ETag и ошибки Genesis API, как опрашивать API без лимитов.
Вопросы и ответы
Тратит ли ответ 304 квоту Genesis API?
Нет. Квоту расходуют только ответы 200; 304 и ошибки бесплатны, но учитываются в лимите запросов в секунду.
Что делать, если в ответе нет ETag?
Опрашивать не чаще meta.freshness_sec и сравнивать meta.updated_at с прошлым ответом: то же значение — снимок не обновлялся.