Insomnia — چیست، کلاینت REST و GraphQL در توسعه

Insomnia چیست و ویژگی‌های کلیدی

Insomnia — یک برنامه چندسکویی (Electron) برای ارسال درخواست‌های HTTP و اشکال‌زدایی API است. از سال 2016 توسط شرکت Kong به عنوان جایگزینی برای 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 مگابایت در برابر ~300 مگابایت)، سریع‌تر راه‌اندازی می‌شود و بدون تحمیل ثبت‌نام کاملاً آفلاین کار می‌کند. Postman اکوسیستم بالغ‌تری با نظارت، سرورهای mock و فضای کاری تیمی ارائه می‌دهد.

انتخاب ابزار متناسب با کار

برای توسعه فردی و تست سریع نقاط پایانی Insomnia به دلیل سبکی و عدم نیاز به ثبت‌نام راحت‌تر است. برای کار تیمی با مجموعه مشترک، یکپارچه‌سازی CI/CD و نظارت بر API تولید، Postman استاندارد صنعت باقی می‌ماند.

سازماندهی فضای کاری و محیط‌ها

Workspace در Insomnia شامل درخت درخواست‌هایی است که به پوشه‌ها تقسیم می‌شود. هر درخواست می‌تواند از نوع HTTP، GraphQL، WebSocket یا gRPC باشد. کشیدن و رها کردن، تکرار و گروه‌بندی درخواست‌ها بر اساس برچسب‌های رنگی پشتیبانی می‌شود. فایل پیکربندی workspace به صورت 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 امکان نوشتن درخواست‌ها با تکمیل خودکار فیلدها بر اساس طرح بارگذاری‌شده را فراهم می‌کند. در سمت راست مستندات نوع‌ها، فیلدها و آرگومان‌ها به صورت زنده نمایش داده می‌شود.

بارگذاری طرح و Introspection

طرح از طریق درخواست 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 نوشته می‌شوند و از طریق API قالب‌ساز با 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 پشتیبانی می‌شوند.

# workflow گیت‌هاب اکشنز با 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 داخلی برای مشاهده تغییرات، ایجاد commit و حل تعارض‌های ادغام مستقیماً از رابط کاربری ارائه می‌دهد.

پیکربندی همگام‌سازی Git

برای اتصال Git، یک پوشه محلی با مخزن ایجاد کنید و آن را به عنوان دایرکتوری ریشه در تنظیمات Insomnia مشخص کنید. برنامه به صورت خودکار تغییرات فایل‌های مجموعه را ردیابی می‌کند و آن‌ها را در پنل Version Control نمایش می‌دهد. عملیات استاندارد پشتیبانی می‌شود: commit، push، pull و مشاهده diff بین نسخه‌ها.

کار تیمی از طریق 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 را ساده می‌کند.