نمای کلی کالکشن عمومی اولین جایی است که بسیاری از مصرف‌کنندگان API با آن روبه‌رو می‌شوند. اگر این بخش خوب نوشته شود، کاربر سریع‌تر می‌فهمد API چه کاری انجام می‌دهد، چطور باید شروع کند و چگونه به اولین پاسخ موفق مثل 200 OK برسد.
نام کالکشن را واضح انتخاب کنید
برای تغییر نام کالکشن، تب Overview کالکشن را باز کنید، روی نام کالکشن کلیک کنید و نام جدید را وارد کنید. نام باید هدف کالکشن را روشن کند. اگر کالکشن شما مرجع API است، نام باید نشان دهد که این کالکشن برای مشاهده endpointها و متدهاست. اگر کالکشن شما برای شروع سریع است، نام باید به کاربر بگوید از اینجا شروع کند.
راهنمای انتخاب نام
- از کلمات قابل جستجو استفاده کنید. نام را بر اساس چیزی انتخاب کنید که مخاطب شما ممکن است جستجو کند؛ مثل حوزه کاری API، کاربرد اصلی یا اصطلاح رایج صنعت.
- کوتاه و توصیفی بنویسید. نام باید با کمترین کلمات بگوید API چه کاری انجام می‌دهد. نام‌های مبهم مثل «User API» معمولا کمک زیادی نمی‌کنند.
- در کل workspace یکدست باشید. اگر چند کالکشن مشابه دارید، الگوی نام‌گذاری آن‌ها را هماهنگ نگه دارید تا کاربر راحت‌تر بین آن‌ها حرکت کند.
توضیح کالکشن را کاربردی بنویسید
در تب Overview روی توضیح کالکشن کلیک کنید و توضیح جدید را بنویسید. توضیح باید کاربر را به اولین درخواست موفق هدایت کند، نه اینکه فقط توضیح بازاری یا عمومی بدهد.
در توضیح چه چیزهایی بیاورید؟
- APIها و سرویس‌ها را معرفی کنید. بگویید هر API چه ارزشی دارد و چه مفاهیم کلیدی باید قبل از استفاده فهمیده شود.
- مسیر شروع را کوتاه کنید. اگر کاربر باید حساب بسازد، کلید بگیرد یا تنظیمی انجام دهد، همانجا لینک و مراحل لازم را بدهید.
- احراز هویت و مجوزها را توضیح دهید. authentication و authorization معمولا بیشترین اصطکاک را ایجاد می‌کنند؛ آن‌ها را مرحله‌به‌مرحله روشن کنید.
- به مستندات تکمیلی لینک دهید. اگر راهنمای شروع، tutorial یا integration guide دارید، لینک آن را اضافه کنید.
- راه‌های دریافت کمک را مشخص کنید. لینک پشتیبانی، انجمن یا منابع جامعه کاربری را قرار دهید تا کاربر در زمان خطا تنها نماند.
منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.