أصبح Playground متاحاً الآن في الـ Dashboard الخاصة بك. ثلاثة endpoints، و cookie jar واحد، وتم تحليل كل header. اختر Single أو Proxy أو Browser، واملأ الـ request، واضغط على Send. ستظهر الـ response في الشاشة نفسها مع الـ status والـ headers والـ body والـ cookies التي تم تحليلها. عندما تكون راضياً عن النتيجة، انسخ أمر cURL الفعال إلى كودك.
هذه ليست صفحة منفصلة أو sandbox خلف URL مختلف. إنه يعمل مباشرةً مقابل الـ API الحية باستخدام مفتاحك الحقيقي. ما تراه في Playground هو ما سيحصل عليه كود الإنتاج (production code) الخاص بك.
كيف يعمل
تقوم بتسجيل الدخول إلى الـ Dashboard، وتختار واحداً من ثلاثة endpoints، ليعيد النموذج بناء نفسه لعرض الحقول التي يقبلها هذا الـ endpoint فعلياً فقط.
- يتلقى Single كلاً من
urlوmethodوheadersوunblockerوproxyوtryJsonDataوfollowRedirectsومجموعة timeout. - يتلقى Proxy المجموعة نفسها مغلفة داخل كتلة
request، بالإضافة إلى فلاتر اختيار الـ proxy (البلد، المدينة، ASN، المجهولية، الحداثة). - يتلقى Browser كلاً من
urlوcookiesوheadersوشروط الانتظار (wait conditions).
عندما تضغط على Send، يقوم الـ Dashboard بالمصادقة على الاستدعاء مقابل حسابك ويرسل طلب POST إلى /api/{endpoint} على api.foura.ai. لا ينتقل مفتاح الـ API الحقيقي الخاص بك عبر الصفحة أبداً. يعد Playground هو المكان الوحيد في الـ Dashboard الذي يمكنك من خلاله إرسال request مدفوع دون الكشف عن المفتاح في المتصفح.
إليك أمر cURL الذي ينتجه الـ Playground لإعادة إنتاج request أساسي من نوع Single:
curl -X POST 'https://api.foura.ai/api/single' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
--data-raw '{
"url": "https://example.com/products",
"method": "GET",
"unblocker": true,
"tryJsonData": true
}'
الصق ذلك في الـ terminal أو في سكربت البناء وسيتصرف تماماً مثل زر Send. نحن لا نغلف الـ payload في غلاف مخصص ولا نعيد تسمية أي من الحقول. يرسل Playground ما يقبله الـ API، نقطة انتهى.
ما تراه في الرد
تعرض لوحة الـ response الـ status الخاصة بالخادم الرئيسي (upstream status)، والوقت الإجمالي، ومعرّف الـ proxy (في مكالمات Proxy) الذي تولى معالجة الـ request. يحصل كل من Body و Headers و Cookies على تبويب خاص به.
Body. يتم عرض الـ JSON المكتشف تلقائياً في عارض قابل للطي. وتنتقل الـ payloads من نوع HTML إلى لوحة معاينة لتتمكن من إلقاء نظرة سريعة على ما أرجعه الموقع المستهدف. ويتحول النص إلى عرض monospace بسيط. يوجد مربع بحث في تبويبي Body و Raw مع إمكانية التنقل بين السابق والتالي.
Headers. عرض محلل مع صف واحد لكل name: value، أو Raw لعرض سلسلة الـ response الكاملة متعددة القفزات (multi-hop). يترك كل إعادة توجيه (redirect) مجموعة الـ headers الخاصة به، لذا فإن تتبع رمز 302 إلى وجهته النهائية يتطلب نقرة واحدة فقط.
Cookies. يقوم الـ jar بتحليل كل سطر Set-Cookie من الـ response، ويتتبع ما إذا كانت كل cookie مخصصة للمضيف فقط (host-only) أو على مستوى النطاق بالكامل (domain-wide) وفقاً للمواصفة (RFC 6265 §5.3)، ويقدم عرضين: بطاقات قابلة للطي لكل مضيف أو القائمة الخام (raw list). قم بتفعيل الـ jar وسيقوم الـ request التالي بسحب الـ cookies المطابقة تلقائياً. بالنسبة لـ Single و Proxy، يعني هذا وجود header باسم Cookie في الـ request الصادر. أما بالنسبة لـ Browser، فيعني ذلك مصفوفة cookies مرفقة بكائن الـ request.
تحفظ الـ Presets إعدادات الـ request بالكامل تحت اسم ووصف معينين، بحيث يمكنك العودة سريعاً إلى "test login on staging" دون إعادة بنائها. يحتفظ الـ History بآخر عشرين عملية تشغيل مع الـ status، و content type، والوقت الإجمالي، والـ proxy المستخدم.
الأثر
الشيء الذي يغيره Playground فعلياً هو حلقة التكرار (iteration loop).
في السابق، كنت تكتب سكربت صغيراً (Node أو Python أو shell)، وتربط مفتاحك، وتستدعي الـ API، وتطبع الـ body، وتعدل header واحداً، ثم تشغله مرة أخرى. ربما يستغرق الأمر عشر دقائق من "أتساءل عما يرجعه هذا الموقع" إلى الحصول على إجابة.
في Playground، تقترب هذه الحلقة من خمس عشرة ثانية. انقر على endpoint، والصق الـ URL، واضغط على Send، وانظر إلى الـ cookies، وغير قيمة unblocker من إيقاف التشغيل إلى التشغيل، واضغط على Send مجدداً. بحلول الوقت الذي تفتح فيه محرر الأكواد الخاص بك، ستكون قد عرفت بالفعل أي نسخة من الـ request تعمل بنجاح على هدفك.
لم نطلق Playground ليستبدل كودك الحقيقي. لقد أطلقناه لكي يتوقف المسار من "هل هذا ممكن على هذا الموقع أساساً" إلى "نعم، إليك أمر cURL الفعال" عن كونه يتطلب مشروعاً جانبياً.
للمستخدمين المتقدمين
بعض الأشياء التي قد لا تكون واضحة من الوهلة الأولى:
تحمل الـ Presets الـ payload بالكامل. ويشمل ذلك مجموعة timeout، وقواعد التحقق (validation rules)، والحد الأقصى لإعادة التوجيه (redirect limit)، وأي headers مخصصة. عندما تحفظ preset، فإنك تأخذ لقطة لـ request تم اختباره، وليس فقط الـ URL. هذا مفيد عندما تحتفظ بمجموعة من اختبارات smoke tests المستقرة عبر الـ endpoints.
الـ cookie jar يعمل لكل جلسة (per-session). فهو يعيش في متصفحك. نحن لا نحتفظ بالـ cookies الملتقطة على جانب الخادم (server-side). قم بإعادة تحميل علامة التبويب بالكامل (Hard-reload) إذا كنت بحاجة إلى حالة نظيفة.
يظل تبويب Raw والنموذج متزامنين. تعرض حقول النموذج نفس الـ JSON الذي يعرضه تبويب Raw. الصق الـ payload في Raw وسيعاد ملء النموذج تلقائياً. وبالتالي، يمكن لزميل عمل أن يرسل request فعالاً في الدردشة، فتلصقه أنت في Raw، ليقوم النموذج بملء نفسه تلقائياً.
تأخذ cookies المتصفح شكل كائن (object-shaped)، وليس شكل header. إذا كنت ترسل cookies إلى الـ endpoint الخاص بـ Browser يدوياً، فإن كل إدخال يتطلب {name, value, domain?, path?, httpOnly?, secure?, sameSite?}. يقوم Playground ببنائها بشكل صحيح عندما يكون الـ jar قيد التشغيل. وإذا كنت تصيغها بنفسك، فإن مطابقة المخطط (schema match) أمر بالغ الأهمية.
تظهر النتائج (Outcomes) في خلاصة نشاطك. عندما يرسل Playground طلباً (request)، فإنه يُحتسب تماماً مثل أي استدعاء آخر مقابل مفتاحك. ستراه في سجل نشاطك (activity log) مع تسمية النتيجة الصحيحة (success، أو client_error، أو application_error، أو rate_limit، أو service_error). هذا مفيد لإعادة إنتاج (repro) استدعاء إنتاجي غير مستقر: أعد تشغيله في Playground، وابحث عنه في سجل النشاط، ثم شارك الرابط مع الفريق.
الخطوة التالية
يعد Playground الخطوة الأولى في مسعى أكبر لجعل الـ Dashboard يفعل ما هو أكثر من مجرد عرض ما قمت به بالفعل. إن الأنماط التي نراها في سجل الـ requests تشكل الميزات التي سنطلقها لاحقاً.
إذا كنت تستخدمه اليوم وشعرت أن هناك شيئاً غير صحيح، مثل حقل لا يطابق المستندات، أو cookie لم تنجُ من إعادة التوجيه (redirect)، أو response يتم عرضه بشكل خاطئ، فهذه هي الملاحظات التي نقرأها أولاً. يرى الـ Dashboard الـ requests، ونحن نرى الاتجاهات.