بعد از ساخت کالکشن‌های عمومی، مرحله مهم بعدی مرتب‌سازی و بهتر کردن تجربه توسعه‌دهنده است. هدف این است که مصرف‌کننده API سریع بفهمد API چه کاری انجام می‌دهد، از کدام درخواست شروع کند و چطور بدون اصطکاک به اولین پاسخ موفق، مثل 200 OK برسد.
قبل از انتشار، داده‌های حساس را بررسی کنید
هر کالکشن عمومی باید از نظر اطلاعات محرمانه بررسی شود. کلید API، توکن، رمز عبور، شناسه داخلی یا داده محیطی نباید در درخواست‌ها، مثال‌ها، متغیرها یا توضیحات باقی بماند. قابلیت Secret Scanner در Postman می‌تواند مقدارهای حساس را پیدا کند و آن‌ها را با placeholder جایگزین کند.
مرتب‌سازی overview کالکشن
نام کالکشن باید هدف آن را روشن کند. توضیح کالکشن هم باید به کاربر بگوید این مجموعه برای چیست، پیش‌نیازها چیست و اولین قدم عملی کدام است. یک overview خوب، مسیر شروع را کوتاه می‌کند و کاربر را از خواندن توضیحات زیاد به اجرای اولین درخواست می‌رساند.
مرتب‌سازی درخواست‌ها
درخواست‌ها باید توانایی‌های اصلی API را نشان دهند. برای هر request توضیح کوتاه بنویسید، پارامترهای مهم را روشن کنید، نمونه پاسخ اضافه کنید و درخواست‌های مرتبط را در folderهای قابل فهم قرار دهید. اگر API چند جریان کاری دارد، ترتیب folderها را بر اساس همان جریان‌ها بچینید.
بهبود تجربه توسعه‌دهنده
کالکشن عمومی فقط فهرست endpointها نیست. برای تجربه بهتر، احراز هویت و authorization را شفاف کنید، متغیرها و environmentهای لازم را معرفی کنید و در صورت نیاز از scriptها و testها استفاده کنید تا کاربر سریع‌تر نتیجه درست بگیرد.
چک‌لیست مرتب‌سازی
- نام کالکشن دقیق و قابل جستجو باشد.
- توضیح کالکشن مسیر شروع سریع را توضیح دهد.
- هر درخواست مستندات کوتاه و مثال عملی داشته باشد.
- folderها بر اساس use case یا جریان کاری چیده شوند.
- احراز هویت، متغیرها و داده‌های نمونه برای کاربر تازه روشن باشد.
منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.