REST API
REST API هو API مبني بأسلوب REST (Representational State Transfer): كل مجموعة بيانات مورد له رابطه، وطريقة HTTP تحدد الإجراء، ولا يحتفظ الخادم بحالة العميل بين الطلبات. وصف روي فيلدينغ هذا الأسلوب في أطروحته للدكتوراه عام 2000.
تفصيل الطلب
طلب معدلات تمويل BTC في كل البورصات:
curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=BTC" \
-H "X-API-Key: $GENESIS_API_KEY"
| الجزء | القيمة | المعنى |
|---|---|---|
| الطريقة | GET | قراءة البيانات |
| الرابط الأساسي | https://api.genesisarbitrage.com/v1 | الخادم وإصدار API |
| المورد | /funding/rates | معدلات تمويل البورصات |
| المعامل | coin=BTC | BTC فقط |
| الترويسة | X-API-Key | مفتاح العميل |
الاستجابة بصيغة JSON: يحمل data عملة BTC مع قائمة بورصات، لكل منها المعدل عن فترة التمويل (funding_pct) والمعدل المحوَّل إلى 8 ساعات (funding_8h_pct). بدون coin يعيد المورد نفسه كل العملات. الحقول موصوفة في قسم معدلات التمويل.
الطرق والحالة
تخبر الطريقة الخادم بما يفعله بالمورد. دلالات الطرق يحددها معيار HTTP، RFC 9110:
GET: جلب البيانات؛ طريقة آمنة لا تغيّر شيئًا على الخادم؛POST: إرسال بيانات للمعالجة؛ تستخدمها Binance لوضع أمر (POST /api/v3/order)؛PUT: إنشاء مورد أو استبداله؛DELETE: الحذف؛ تستخدمه Binance لإلغاء أمر (DELETE /api/v3/order).
Genesis API يقدّم البيانات فقط، لذلك كل نقاط نهايته GET.
انعدام الحالة (stateless) يعني أن كل طلب يحمل كل ما يحتاجه: المفتاح والمورد والمرشحات. الخادم لا يتذكر الاستدعاءات السابقة وGET لا يغيّر شيئًا، لذا يمكن تكرار الطلب بعد انتهاء المهلة أو بعد 503: النتيجة تتوقف على الطلب نفسه وعلى البيانات الحالية فقط. ولتجنب تنزيل بيانات لم تتغير يرسل Genesis API ETag: الطلب مع If-None-Match يحصل على 304 إذا لم يتغير شيء.
REST مقابل WebSocket
| REST API | WebSocket | |
|---|---|---|
| التفاعل | طلب واستجابة | تدفق رسائل في الاتجاهين |
| من يبدأ | العميل | أي طرف بعد الاتصال |
| يناسب | اللقطات والمرشحات والسجل | تدفقات الصفقات ودفتر الأوامر |
| في Genesis API | كل نقاط النهاية | غير متاح |
مع REST تحصل على التحديثات بالاستطلاع (polling): يكرر البرنامج الطلب بفاصل زمني. يحدّث Genesis API مخرجاته كل meta.freshness_sec ثانية، من 60 في Trial إلى 5 في Max، فالاستطلاع الأسرع لا يفيد.
انظر أيضًا: نقطة النهاية، WebSocket، صيغة الاستجابة، الدرس: أول طلب API مع HTTP والترويسات وJSON.
أسئلة وأجوبة
ما الفرق بين REST API وAPI عمومًا؟
API هو أي مجموعة قواعد تتخاطب بها البرامج. أما REST API فحالة خاصة فوق HTTP: موارد على روابط وطرق قياسية وطلبات لا تعتمد على ما سبقها.
بأي صيغة يستجيب REST API؟
REST لا يحدد صيغة: قد تكون JSON أو XML أو غيرهما. يستجيب Genesis API بصيغة JSON مع ضغط gzip.