درخواست‌های داخل کالکشن عمومی باید توانایی‌های API را واضح نشان دهند و مصرف‌کننده را به اولین پاسخ موفق، مثل 200 OK، برسانند. هر درخواست، مثال و folder باید به کاربر کمک کند بفهمد API در دنیای واقعی چطور استفاده می‌شود.
درخواست‌های مهم را اضافه کنید
برای اضافه کردن request، کنار کالکشن گزینه View more actions و سپس Add request را انتخاب کنید. اگر کالکشن شما مرجع API است، endpointها و متدهای HTTP عمومی را اضافه کنید. اگر کالکشن overview است، درخواست‌هایی را انتخاب کنید که کاربر را سریع وارد کاربردهای اصلی API می‌کند.
راهنمای انتخاب requestها
- برای هر عملیات یا use case یک درخواست اصلی داشته باشید. چند request مشابه برای یک کار، کاربر تازه را گیج می‌کند. برای حالت‌های مختلف بهتر است از example استفاده کنید.
- workflowهای واقعی را نشان دهید. اگر API شما چند کاربرد مهم دارد، requestهایی اضافه کنید که آن کاربردها را قدم‌به‌قدم نمایش دهند.
برای درخواست‌ها example بسازید
یک request را باز کنید، آن را با Send اجرا کنید و سپس در پنل پاسخ گزینه Save Example را انتخاب کنید. مثال‌ها به کاربر نشان می‌دهند پاسخ موفق یا حالت‌های مختلف API چه شکلی است.
اگر یک عملیات می‌تواند چند نتیجه یا سناریوی متفاوت داشته باشد، به جای ساخت چند request تکراری، برای همان request چند example بسازید. این کار کالکشن را تمیزتر و قابل فهم‌تر نگه می‌دارد.
درخواست‌ها را مستند کنید
در تب Overview کالکشن، گزینه View complete documentation را باز کنید. برای هر request، نام روشن و توضیح کوتاه بنویسید. توضیح نباید بیش از حد طولانی باشد، چون باید فضای کافی برای wizard شروع سریع request باقی بماند.
برای یکدستی، همان اصول نام‌گذاری و توضیح‌نویسی کالکشن را برای requestها هم رعایت کنید: نام کوتاه، هدف روشن، توضیح عملی و بدون اصطلاحات غیرضروری.
کالکشن را با folder مرتب کنید
کنار کالکشن یا کنار هر folder، گزینه View more actions و سپس Add folder را انتخاب کنید. folderها باید پیمایش کالکشن را ساده کنند، نه اینکه فقط دسته‌بندی اداری بسازند.
- مراحل onboarding را بازتاب دهید. اگر در توضیح کالکشن چند قدم برای شروع نوشته‌اید، folderها را هم بر همان اساس بچینید.
- موارد پایه را پوشش دهید. بخش‌هایی مثل authentication، authorization و اولین درخواست موفق را واضح قرار دهید.
- use caseهای مهم را جدا کنید. برای جریان‌های کاری مهم مثل ثبت سفارش، پرداخت یا گزارش‌گیری folder بسازید.
- یک folder پشتیبانی در نظر بگیرید. می‌توانید خطاهای رایج، پاسخ‌های ناموفق و روش رفع مشکل را در یک بخش جدا بگذارید.
- از نیاز کاربران واقعی یاد بگیرید. پرسش‌های پشتیبانی و انجمن‌ها را بررسی کنید و مشکلات پرتکرار را در کالکشن پاسخ دهید.
منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.