ETag و If-None-Match
ETag هدر پاسخ HTTP است که برچسب نسخهٔ داده را حمل میکند: تا زمانی که منبع تغییر نکند، برچسب هم همان میماند. کلاینت برچسب را در هدر If-None-Match پس میفرستد و اگر سرور هنوز همان نسخه را دارد، با 304 Not Modified و بدون بدنه پاسخ میدهد. هر دو هدر در RFC 9110 (معناشناسی HTTP، 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 کیلوبایت فشرده است و برچسبش تقریباً هر 15 دقیقه عوض میشود. در 30 روز این یعنی 30 × 24 × 60 = 43,200 درخواست. با If-None-Match فقط 30 × 24 × 4 = 2,880 درخواست کل بخش را دانلود میکنند؛ 40,320 درخواست دیگر با 304، بدون بدنه و بدون کسر سهمیه برمیگردند. ترافیک از حدود 26 گیگابایت به 1.7 گیگابایت میرسد.
همچنین ببینید: پولینگ API، HTTP 429، تازگی داده، قالب پاسخ، ETag و خطاهای Genesis API، چگونه API را بدون رسیدن به محدودیتها پولینگ کنیم.
پرسش و پاسخ
آیا پاسخ 304 از سهمیهٔ Genesis API مصرف میکند؟
خیر. فقط پاسخهای 200 سهمیه مصرف میکنند؛ 304 و خطاها رایگاناند اما در محدودیت درخواست در ثانیه شمرده میشوند.
اگر پاسخ ETag نداشته باشد چه کنم؟
بیشتر از meta.freshness_sec درخواست نفرستید و meta.updated_at را با پاسخ قبلی مقایسه کنید: مقدار یکسان یعنی اسنپشات بهروز نشده است.