تجربه توسعه‌دهنده در کالکشن عمومی فقط به داشتن endpointها محدود نیست. کالکشن باید احراز هویت، متغیرها، محیط‌ها، scriptها و testها را طوری آماده کند که مصرف‌کننده API با کمترین اصطکاک به اولین پاسخ موفق برسد.
قبل از عمومی کردن کالکشن، داده‌های حساس را بررسی کنید. اگر Postman کلید API، توکن یا مقدار مشابهی پیدا کند، آن را با placeholder جایگزین می‌کند. با این حال، بهتر است خودتان هم requestها، exampleها، متغیرها و توضیحات را دقیق مرور کنید.
احراز هویت و مجوزها را آماده کنید
Postman پیشنهاد می‌کند برای دامنه خود از Guided Auth با OAuth ۲.۰ استفاده کنید. وقتی این تنظیم فعال باشد و کاربر از endpointهای دامنه شما استفاده کند، Postman او را در مسیر احراز هویت راهنمایی می‌کند. این روش معمولا سریع‌ترین و روان‌ترین تجربه را برای مصرف‌کننده API می‌سازد.
راه‌اندازی Guided Auth برای دامنه
- در header روی پروفایل خود کلیک کنید و نام سازمان یا تیم را انتخاب کنید.
- بخش Guided Auth را باز کنید.
- نام API، base URL و نوع OAuth ۲.۰ را وارد کنید.
- دامنه را verify کنید و جزئیات authentication و authorization را کامل کنید.
اگر OAuth ۲.۰ برای شما مناسب نیست، Postman از چند نوع authorization دیگر هم پشتیبانی می‌کند.
تنظیم auth در سطح کالکشن
اگر هنوز آماده Guided Auth نیستید، می‌توانید authorization را در سطح کالکشن تنظیم کنید. درخواست‌های داخل کالکشن، جزئیات authorization را از کالکشن به ارث می‌برند. کالکشن را باز کنید، به تب Authorization بروید، Auth Type را انتخاب کنید و جزئیات لازم را وارد کنید. وقتی مصرف‌کننده کالکشن را fork کند، بخش‌های باقی‌مانده را با مقادیر خودش کامل می‌کند.
متغیرها و environmentها را بسازید
متغیرها کمک می‌کنند کاربر مقدارهایی مثل API key، base URL یا شناسه‌های تکراری را فقط یک بار وارد کند و در چند request استفاده کند. برای کالکشن عمومی از global variables استفاده نکنید، چون مصرف‌کنندگان نمی‌توانند global variables شما را fork کنند. به جای آن از collection variables و environment variables استفاده کنید.
متغیرهای کالکشن
برای ساخت collection variable، کالکشن را باز کنید، به تب Variables بروید و متغیرهای لازم را اضافه کنید. نام متغیرها را واضح انتخاب کنید تا کاربر بداند چه مقداری باید جایگزین کند.
environment و environment variable
environment مجموعه‌ای از متغیرها برای یک context مشخص است. برای مثال می‌توانید یک environment برای sandbox و یک environment برای production بسازید. اگر مقدار API key یا base URL در هر محیط متفاوت است، environment کمک می‌کند کاربر با تغییر محیط، مقادیر مناسب را هم تغییر دهد.
برای ساخت environment، از sidebar گزینه Add و سپس Environment را انتخاب کنید و متغیرهای مورد نیاز را اضافه کنید.
environmentها را به کالکشن pin کنید
اگر environment را به کالکشن pin کنید، وقتی مصرف‌کننده کالکشن را fork می‌کند، environmentهای pin شده هم به‌صورت پیش‌فرض همراه آن fork می‌شوند. کالکشن را باز کنید، در workbench از environment selector محیط مورد نظر را پیدا کنید و گزینه Pin to collection را انتخاب کنید.
می‌توانید یکی از environmentهای pin شده را به عنوان default pinned environment تنظیم کنید. در این حالت، وقتی کاربر کالکشن را fork می‌کند، Postman همان environment را به‌صورت خودکار فعال می‌کند.
برای کالکشن script و test بنویسید
pre-request script و post-response script می‌توانند کارهای تکراری را خودکار کنند، داده را تغییر دهند، منطق شرطی اضافه کنند یا به کاربر بازخورد فوری بدهند. برای مثال می‌توانید تاریخ را به فرمت مورد انتظار API تبدیل کنید، وجود یک key در پاسخ را بررسی کنید یا access token دریافتی را برای درخواست‌های بعدی ذخیره کنید.
برای نوشتن script، یک request، folder یا collection را باز کنید، وارد تب Scripts شوید و بسته به نیاز Pre-request یا Post-response را انتخاب کنید.
منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.