Postman: چیست، تست API و کار با درخواست‌ها

Postman چیست و امکانات کلیدی

Postman پلتفرمی برای توسعه و تست API است که به‌صورت برنامه دسکتاپ (Windows, macOS, Linux) و نسخه وب در دسترس است. Postman که در ابتدا در سال ۲۰۱۲ به‌عنوان افزونه Chrome ساخته شد، به اکوسیستمی کامل با پشتیبانی از مانیتورینگ، mock-سرورها و تولید کد کلاینتی تبدیل شد.

فرمت‌های درخواست و پاسخ

Postman از تمام متدهای HTTP پشتیبانی می‌کند: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. بدنه درخواست می‌تواند در قالب‌های JSON، XML، form-data، x-www-form-urlencoded و binary باشد. پاسخ با برجسته‌سازی سینتکس، Pretty-print و امکان مشاهده هدرهای خام نمایش داده می‌شود.

پشتیبانی از احراز هویت

انواع داخلی احراز هویت شامل Bearer Token، Basic Auth، Digest Auth، OAuth 1.0، OAuth 2.0، API Key و AWS Signature است. Postman هدر Authorization را طبق نوع انتخاب‌شده به‌صورت خودکار اضافه می‌کند که تست اندپوینت‌های محافظت‌شده را بدون کپی دستی توکن‌ها سرعت می‌بخشد.

رابط Postman و ناوبری

رابط Postman از پنل کناری (Collections, APIs, Environments)، ناحیه کاری (Request Builder/Response Viewer) و پنل پایینی (Console, Runner) تشکیل شده است. تب Params امکان ویرایش پارامترهای query در URL را به‌صورت جدول فراهم می‌کند و تب Headers برای مدیریت هدرهای HTTP است.

Postman Console

Console (View → Show Postman Console) تمام درخواست‌ها و پاسخ‌های شبکه را به‌ترتیب زمانی، از جمله ریدایرکت‌های میانی و هدرها را ثبت می‌کند. این ابزار برای اشکال‌زدایی جریان‌های پیچیده OAuth و زنجیره‌های ریدایرکت که Response Viewer استاندارد فقط نتیجه نهایی را نشان می‌دهد، ضروری است.

Workspaces و کار تیمی

Postman از فضاهای کاری تیمی (Workspaces) با نسخه‌گذاری مجموعه‌ها از طریق Fork و Merge پشتیبانی می‌کند. اعضای تیم می‌توانند روی درخواست‌ها نظر بدهند، تغییرات پیشنهاد دهند و مجموعه‌ها را در زمان واقعی همگام کنند. Public Workspace امکان انتشار مستندات API برای توسعه‌دهندگان خارجی را فراهم می‌کند.

ایجاد و ارسال درخواست‌های HTTP

درخواست پایه در Postman با انتخاب متد HTTP و وارد کردن URL در نوار آدرس ایجاد می‌شود. پس از ارسال، پاسخ در پنل پایینی با کد وضعیت، زمان اجرا و اندازه نمایش داده می‌شود. پارامترهای درخواست هنگام ورود به‌صورت خودکار کدگذاری می‌شوند.

متغیرهای پویا و اسنیپت‌ها

در URL و بدنه درخواست می‌توان از متغیرهای پویا به‌فرمت {`{`}}$variable${`}`} استفاده کرد. متغیرهای داخلی {`{`}$guid${`}`}، {`{`}$timestamp${`}`} و {`{`}$randomInt${`}`} برای هر درخواست مقادیر یکتا تولید می‌کنند. اسنیپت‌های کد از طریق دکمه Code () در دسترس هستند که درخواست معادل را به cURL، Python، JavaScript، Kotlin، Swift و زبان‌های دیگر تولید می‌کند.

// نمونه اسکریپت در Pre-request: تولید امضای HMAC
const timestamp = Date.now().toString();
const secret = pm.environment.get("api_secret");
const hash = CryptoJS.HmacSHA256(timestamp, secret);
pm.request.headers.add({
    key: "X-Signature",
    value: hash.toString()
});

مجموعه‌ها و متغیرهای محیطی

مجموعه‌ها گروه‌هایی از درخواست‌های مرتبط هستند که بر اساس پروژه یا ماژول عملکردی ترکیب می‌شوند. هر مجموعه می‌تواند شامل پوشه‌های تو در تو، هدرهای مشترک و اسکریپت‌های Pre-request باشد که قبل از هر درخواست در مجموعه اجرا می‌شوند. ترتیب درخواست‌ها با کشیدن و رها کردن تعیین می‌شود.

متغیرهای محیطی و متغیرهای سراسری

Postman از پنج سطح متغیر پشتیبانی می‌کند: global، collection، environment، data و local. اولویت حل تعارض — از محلی به سراسری. فایل‌های Environment شامل جفت‌های کلید-مقدار برای محیط‌های مختلف هستند: development، staging، production. تغییر محیط، همه URLها و توکن‌ها را به‌صورت خودکار تغییر می‌دهد.

خودکارسازی تست API از طریق اسکریپت‌ها

Postman امکان نوشتن تست‌های JavaScript در تب Tests را فراهم می‌کند که پس از دریافت پاسخ اجرا می‌شوند. تست‌ها کد وضعیت، بدنه پاسخ، هدرها و زمان اجرا را بررسی می‌کنند. نتایج در پنل Test Results با نشانگر رنگی قبولی نمایش داده می‌شوند.

کتابخانه pm و زنجیره‌سازی درخواست‌ها

شی pm روش‌هایی برای کار با پاسخ فراهم می‌کند: pm.response، pm.expect، pm.variables. زنجیره‌سازی درخواست‌ها از طریق ذخیره داده‌های پاسخ یک درخواست در متغیر و استفاده از آن در درخواست بعدی انجام می‌شود. این اساس ساخت تست‌های یکپارچه‌سازی و بررسی منطق کسب‌وکار از طریق دنباله‌ای از فراخوانی‌های API است.

// تست: بررسی ساختار پاسخ و ذخیره توکن
pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
});

const json = pm.response.json();
pm.environment.set("auth_token", json.data.token);

Collection Runner و Newman

Collection Runner همه درخواست‌های مجموعه را به‌صورت متوالی اجرا می‌کند و در هر مرحله تست‌ها را انجام می‌دهد. Newman نسخه کنسولی Postman برای پایپ‌لاین‌های CI/CD (Jenkins, GitHub Actions, GitLab CI) است. Newman گزارش را به‌فرمت‌های JSON، JUnit و HTML برای یکپارچه‌سازی با سیستم‌های مانیتورینگ صادر می‌کند.

کار با GraphQL و WebSocket

درخواست‌های GraphQL در Postman از طریق POST به یک اندپوینت واحد با بدنه JSON ارسال می‌شوند. تب GraphQL (Beta) ویرایشگر بصری با برجسته‌سازی سینتکس، تکمیل خودکار فیلدها و اسکیما فراهم می‌کند. متغیرهای درخواست در پنل جداگانه Variables منتقل می‌شوند.

تست WebSocket و Socket.IO

Postman از اتصالات WebSocket از طریق رابط جداگانه با پنل پیام پشتیبانی می‌کند. می‌توان پیام‌های متنی و باینری ارسال کرد، تاریخچه اتصال را مشاهده کرد و هنگام قطعی به‌صورت خودکار دوباره متصل شد. کلاینت Socket.IO در حالت سازگاری با پروتکل Engine.IO کار می‌کند.

// تست WebSocket در Postman از طریق pm API
const ws = new WebSocket("wss://echo.websocket.org");
ws.onmessage = (event) => {
    pm.test("Echo response received", () => {
        pm.expect(event.data).to.eql("Hello");
    });
};

mock-سرورها و مانیتورینگ در Postman

mock-سرورها امکان شبیه‌سازی اندپوینت‌های API را بر اساس مجموعه‌های موجود فراهم می‌کنند. این زمانی مفید است که بک‌اند هنوز آماده نیست اما فرانت‌اند یا اپلیکیشن موبایل در حال توسعه است. mock-سرور نمونه پاسخ از مجموعه را با هدرهای صحیح و کد وضعیت برمی‌گرداند.

ایجاد mock-سرور

mock-سرور از مجموعه با یک کلیک ایجاد می‌شود: مجموعه را انتخاب کنید → Mock Servers → Add a new mock server. Postman یک URL یکتا تولید می‌کند که می‌توان به‌جای API واقعی در کد اپلیکیشن استفاده کرد. برای هر درخواست مجموعه، mock Example Response ذخیره‌شده را برمی‌گرداند که امکان بررسی UI قبل از تکمیل بک‌اند را فراهم می‌کند.

مانیتورینگ API از طریق Postman Monitors

Monitors مجموعه را طبق برنامه (هر ۵ دقیقه، ساعت یا روز) اجرا می‌کنند و در دسترس بودن و صحت API را بررسی می‌کنند. در صورت شکست تست، مانیتور اعلان به ایمیل یا Slack ارسال می‌کند. مانیتورینگ از ابر Postman کار می‌کند، به سرور جداگانه نیاز ندارد و در پلن رایگان تا ۱۰٬۰۰۰ درخواست در ماه را پشتیبانی می‌کند.

// تست برای مانیتورینگ: بررسی زمان پاسخ
pm.test("Response time < 2000ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

pm.test("Content-Type is JSON", () => {
    pm.response.to.have.header("Content-Type");
});

امنیت و مدیریت اسرار

Postman مکانیسم‌هایی برای کار امن با کلیدهای API فراهم می‌کند. متغیرهای نوع Secret رمزگذاری می‌شوند و در رابط نمایش داده نمی‌شوند. برای کار تیمی از Workspace با نقش‌های Admin، Editor و Viewer استفاده کنید.

رمزگذاری متغیرها

هنگام ایجاد متغیر محیطی نوع Secret را انتخاب کنید — مقدار در همه رابط‌ها با ستاره پنهان می‌شود. اسرار هنگام اشتراک‌گذاری به مجموعه صادر نمی‌شوند و در لاگ‌های Newman نمایش داده نمی‌شوند. توصیه می‌شود رمزها و توکن‌ها را فقط در متغیرهای Secret نگهداری کنید.

یکپارچه‌سازی با Vault

Postman از یکپارچه‌سازی با HashiCorp Vault و AWS Secrets Manager پشتیبانی می‌کند. اسکریپت‌های Pre-request می‌توانند اسرار را از ذخیره‌گاه خارجی به‌صورت پویا درخواست کنند و ذخیره داده‌های حساس در فایل‌های مجموعه و محیط را حذف کنند.

امنیت و مدیریت اسرار

Postman مکانیسم‌هایی برای کار امن با کلیدهای API فراهم می‌کند. متغیرهای نوع Secret رمزگذاری می‌شوند و در رابط نمایش داده نمی‌شوند. برای کار تیمی از Workspace با نقش‌های Admin، Editor و Viewer استفاده کنید.

رمزگذاری متغیرها

هنگام ایجاد متغیر محیطی نوع Secret را انتخاب کنید — مقدار در همه رابط‌ها با ستاره پنهان می‌شود. اسرار هنگام اشتراک‌گذاری به مجموعه صادر نمی‌شوند و در لاگ‌های Newman نمایش داده نمی‌شوند. توصیه می‌شود رمزها و توکن‌ها را فقط در متغیرهای Secret نگهداری کنید.

یکپارچه‌سازی با Vault

Postman از یکپارچه‌سازی با HashiCorp Vault و AWS Secrets Manager پشتیبانی می‌کند. اسکریپت‌های Pre-request می‌توانند اسرار را از ذخیره‌گاه خارجی به‌صورت پویا درخواست کنند و ذخیره داده‌های حساس در فایل‌های مجموعه و محیط را حذف کنند.