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
الاستجابة 200 وحدها تُحتسب استدعاءً في Genesis API: أما 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، حداثة البيانات، صيغة استجابة Genesis API وETag والأخطاء، كيف تستعلم من API دوريا دون الوصول إلى الحدود.
أسئلة وأجوبة
هل تستهلك استجابة 304 من حصة Genesis API؟
لا. الاستجابات 200 وحدها تستهلك الحصة؛ أما 304 والأخطاء فمجانية، لكنها تُحتسب ضمن حد الطلبات في الثانية.
ماذا أفعل إذا لم تحمل الاستجابة ETag؟
استعلم بوتيرة لا تزيد على meta.freshness_sec وقارن meta.updated_at بالاستجابة السابقة: القيمة نفسها تعني أن اللقطة لم تُحدَّث.