کالکشن‌های عمومی مهم‌ترین بخش تجربه مصرف‌کننده در شبکه API Postman هستند. وقتی API را عمومی منتشر می‌کنید، کاربران باید بتوانند کالکشن را fork کنند، درخواست‌ها را بفهمند و در کمترین زمان به اولین پاسخ موفق، مثل 200 OK برسند.
چه کالکشن‌هایی لازم است؟
برای یک API عمومی معمولا دو نوع کالکشن مفید است: کالکشن مرجع API و کالکشن overview. کالکشن مرجع، endpointها و متدهای HTTP را با جزئیات نشان می‌دهد. کالکشن overview مسیر شروع سریع را فراهم می‌کند و به کاربر کمک می‌کند کاربردهای اصلی API را مرحله‌به‌مرحله تجربه کند.
محافظت از داده‌های حساس
قبل از عمومی کردن هر کالکشن، مطمئن شوید کلید API، توکن، رمز عبور، داده داخلی یا مقدار محرمانه داخل درخواست‌ها، مثال‌ها و متغیرها باقی نمانده باشد. قابلیت Secret Scanner در Postman می‌تواند مقادیر حساس مانند کلیدها و توکن‌ها را شناسایی کند و آن‌ها را با placeholder جایگزین کند.
ساخت کالکشن مرجع API
اگر تعریف OpenAPI دارید، بهترین مسیر این است که آن را وارد Postman کنید. workspace عمومی خود را باز کنید، از منوی options گزینه Import را انتخاب کنید، فایل یا لینک تعریف API را وارد کنید، روش import را مشخص کنید و در صورت نیاز تنظیمات import را بررسی کنید. بعد از انتخاب Import، Postman از تعریف OpenAPI یک کالکشن قابل استفاده می‌سازد.
اگر تعریف OpenAPI ندارید، می‌توانید کالکشن را دستی بسازید. گزینه Add و سپس Collection را انتخاب کنید، نام و توضیح مناسب بنویسید، درخواست‌ها و مثال‌ها را اضافه کنید، برای هر درخواست مستندات کوتاه و دقیق بنویسید و درخواست‌ها را با folderها مرتب کنید.
ساخت کالکشن overview
کالکشن overview مکمل کالکشن مرجع است. این کالکشن باید نقطه شروع ساده‌ای برای کاربران تازه باشد: API را معرفی کند، چند درخواست کلیدی را نشان دهد، مسیر رسیدن به پاسخ موفق را کوتاه کند و چند workflow یا use case مهم را نمایش دهد.
برای ساخت آن، در workspace گزینه Add و سپس Collection را انتخاب کنید. نامی بگذارید که هدف کالکشن را روشن کند، توضیح کوتاه و کاربردی بنویسید، چند درخواست نمونه و مثال پاسخ اضافه کنید و آن‌ها را به ترتیبی بچینید که کاربر از ساده‌ترین قدم شروع کند.
چک‌لیست کوتاه
- نام کالکشن باید هدف آن را واضح کند.
- توضیحات باید مسیر شروع سریع را توضیح دهد.
- برای درخواست‌های مهم example response قرار دهید.
- Folderها را بر اساس جریان کاری یا حوزه API تنظیم کنید.
- بعد از تغییر API، کالکشن‌ها را هم به‌روز کنید.
منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.