Insomnia — ما هو، عميل REST و GraphQL في التطوير

ما هو Insomnia والميزات الرئيسية

Insomnia هو تطبيق متعدد المنصات (Electron) لإرسال طلبات HTTP وتصحيح أخطاء API. تطوره شركة Kong منذ عام 2016 كبديل لـ Postman مع التركيز على سرعة العمل والخصوصية: تُخزن البيانات محلياً، والمزامنة السحابية اختيارية وتتطلب التسجيل.

الواجهة والتنقل

تنقسم النافذة الرئيسية إلى ثلاثة أعمدة: على اليسار شجرة الطلبات (Workspace)، وفي المنتصف محرر الطلبات مع تبويبات Params و Headers و Body، وعلى اليمين لوحة الاستجابة مع أوضاع Pretty و Raw و Preview. السمة الداكنة مفعّلة افتراضياً، وتُدعم السمات المخصصة عبر متغيرات CSS.

توليد الكود

يدعم Insomnia تصدير الطلب إلى كود بأكثر من 20 لغة وأطر عمل: cURL و HTTPie و Python Requests و JavaScript Fetch/Axios و Kotlin OkHttp و Swift URLSession و Java Unirest و Ruby Net::HTTP وغيرها. يأخذ المولّد في الاعتبار الترويسات وجسم الطلب ونوع المصادقة، ما يسرّع دمج API في كود التطبيق.

Insomnia مقابل Postman: مقارنة عملاء API

Insomnia و Postman يحلان نفس المهمة لكن بأولويات مختلفة. Insomnia أخف (~80 MB مقابل ~300 MB)، ويبدأ التشغيل أسرع ويعمل بالكامل دون اتصال دون فرض التسجيل. يقدم Postman نظاماً بيئياً أكثر نضجاً مع مراقبة وخوادم mock ومساحات عمل جماعية.

اختيار الأداة المناسبة للمهمة

للتطوير الفردي والاختبار السريع لنقاط النهاية، يعد Insomnia أكثر ملاءمة بفضل خفته وعدم الحاجة للتسجيل. وللعمل الجماعي مع مجموعة مشتركة وتكامل CI/CD ومراقبة API الإنتاجية، يظل Postman معيار الصناعة.

تنظيم مساحة العمل والبيئات

مساحة العمل في Insomnia تحتوي على شجرة طلبات مقسمة إلى مجلدات. يمكن أن يكون كل طلب من نوع HTTP أو GraphQL أو WebSocket أو gRPC. يُدعم السحب والإفلات والنسخ وتجميع الطلبات حسب التسميات الملونة. يُخزن ملف إعداد مساحة العمل بصيغة JSON.

متغيرات البيئة مع الوراثة

يدعم Insomnia البيئات المتداخلة (Sub Environments) التي ترث متغيرات البيئة الأم. يسمح ذلك بتحديد عنوان URL أساسي في البيئة العامة وإعادة تعريف المعلمات المختلفة فقط لبيئات متعددة. تُستبدل المتغيرات عبر الصيغة {`{`}_variable${`}`}.

// مثال على بنية بيئة Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

العمل مع GraphQL في Insomnia

يوفر Insomnia واحداً من أفضل محررات GraphQL بين عملاء API. يتيح تبويب GraphQL Query كتابة استعلامات مع الإكمال التلقائي للحقول بناءً على المخطط المحمّل. وعلى اليمين تُعرض توثيقات الأنواع والحقول والوسائط في الوقت الفعلي.

تحميل المخطط والاستبطان

يُحمَّل المخطط عبر طلب GraphQL Introspection إلى نقطة النهاية. يخزن Insomnia المخطط محلياً في الذاكرة المؤقتة ويحدّثه تلقائياً عند التغييرات. بعد التحميل، يتوفر الإكمال التلقائي (Ctrl+Space) والتحقق من صحة الاستعلام ومعاينة الأخطاء المحتملة قبل الإرسال.

# استعلام GraphQL مع متغيرات في Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

الإضافات وتوسيع الوظائف

يحتوي Insomnia Plugin Hub على أكثر من 100 إضافة توسع وظائف العميل. تُثبت الإضافات عبر قائمة Preferences ← Plugins أو يدوياً عبر npm. تشمل الفئات الشائعة توليد بيانات الاختبار والتصدير إلى صيغ مختلفة ومحللي استجابة مخصصين. تخضع كل إضافة للمراجعة الإلزامية قبل نشرها في المركز العام للمطورين.

إضافات شائعة

• insomnia-plugin-faker — توليد بيانات وهمية (اسم، بريد إلكتروني، هاتف) لطلبات الاختبار.
• insomnia-plugin-aws4 — توقيع الطلبات وفق AWS Signature Version 4 للعمل مع Amazon API Gateway و S3.
• insomnia-plugin-utils — أدوات مساعدة للعمل مع التواريخ والتجزئة وترميز Base64 مباشرة في الطلبات.

تُكتب الإضافات بلغة JavaScript وتتفاعل مع Insomnia عبر واجهة القوالب (response.*، request.*، environment.*). يتطلب تطوير الإضافة معرفة أساسية بـ Node.js ونشرها عبر حزمة npm بوسم insomnia-plugin.

CLI وأتمتة الاختبار

Inso CLI هو أداة سطر أوامر مدمجة في Insomnia لتشغيل الطلبات والاختبارات من الطرفية. يشغّل Inso طلبات فردية أو مجموعات كاملة، ويصدّر النتائج إلى JSON، ويمكن دمجه في خطوط CI/CD. ينفذ الأمر inso run collection جميع الطلبات في المجموعة تباعاً.

مثال على التكامل في GitHub Actions

يعمل Inso CLI في حاويات Docker ووضع headless، ما يسمح باستخدامه في GitHub Actions و GitLab CI. يُوصف إعداد التشغيل في ملف YAML مع تحديد المسار إلى المجموعة المُصدَّرة والبيئة. تُدعم التأكيدات على رمز الحالة وجسم الاستجابة عبر سكربتات JavaScript.

# سير عمل GitHub Actions مع Inso CLI
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

تكامل Insomnia مع Git والعمل الجماعي

يدعم Insomnia مزامنة المجموعات عبر Git. تُخزن ملفات المجموعات بصيغة JSON ويمكن إضافتها إلى مستودع المشروع. يوفر Insomnia عميل Git مدمجاً لعرض التغييرات وإنشاء الالتزامات وحل تعارضات الدمج مباشرة من الواجهة.

إعداد مزامنة Git

لربط Git، أنشئ مجلداً محلياً بمستودع وحدده كدليل جذر في إعدادات Insomnia. يتتبع التطبيق تلقائياً التغييرات في ملفات المجموعة ويعرضها في لوحة Version Control. تُدعم العمليات القياسية: commit و push و pull وعرض الفروق بين الإصدارات.

العمل الجماعي عبر Insomnia Cloud

للمشاريع دون Git، يقدم Insomnia مزامنة سحابية عبر Insomnia Cloud. تشمل الخطة المجانية حتى 3 أعضاء في الفريق ونسخاً احتياطياً تلقائياً للمجموعات. تضيف الخطط المدفوعة إدارة الوصول وتدقيق التغييرات والدعم ذا الأولوية.

Design Mode وتوليد المواصفات

يتيح Design Mode في Insomnia إنشاء مواصفات API بصيغة OpenAPI 3.0. يعمل الوضع كمحرر مرئي: حدد نقاط النهاية ومخططات البيانات دون كتابة YAML يدوياً. يمكن تصدير المواصفة إلى JSON أو YAML.

توليد مجموعة من OpenAPI

يستورد Insomnia مواصفات OpenAPI وينشئ مجموعة طلبات لكل نقطة نهاية. تُحوَّل المسارات والمخططات إلى طلبات HTTP جاهزة. تعد هذه الميزة مفيدة عند التكامل مع الخدمات المصغرة حيث تُخزن المواصفة في مستودع منفصل للفريق.

وسم الطلبات

يمكن تخصيص تسمية ملونة لكل طلب: red و blue و green و orange و purple. يعمل التصفية حسب الوسوم عبر شريط البحث بغض النظر عن بنية المجلدات، ما يبسّط التنقل في المشاريع التي تضم مئات نقاط النهاية والعديد من الوحدات.

Design Mode وتوليد المواصفات

يتيح Design Mode في Insomnia إنشاء مواصفات API بصيغة OpenAPI 3.0 مباشرة داخل التطبيق. يعمل الوضع كمحرر مرئي: حدد نقاط النهاية ومخططات البيانات والمعاملات دون كتابة YAML يدوياً. يمكن تصدير المواصفة إلى JSON أو YAML لنشرها في المستودعات.

توليد مجموعة من OpenAPI

يستورد Insomnia مواصفات OpenAPI الحالية وينشئ تلقائياً مجموعة طلبات لكل نقطة نهاية. تُحوَّل المسارات والمخططات إلى طلبات HTTP جاهزة بأنواع بيانات صحيحة. تعد هذه الميزة مفيدة عند التكامل مع الخدمات المصغرة حيث تُخزن المواصفة وتحافظ عليها فريق تطوير خلفي منفصل.

وسم الطلبات وتصفيتها

لتنظيم عدد كبير من الطلبات، يدعم Insomnia الوسم: يمكن تخصيص تسمية ملونة لكل طلب: red و blue و green و orange و purple. يعمل التصفية حسب الوسوم عبر شريط البحث بغض النظر عن بنية المجلدات، ما يبسّط التنقل في المشاريع التي تضم مئات نقاط النهاية والعديد من الوحدات الوظيفية لـ API.