مستندسازی API برای مصرفکننده
اگر سرویسی میسازید که کس دیگری مصرفش میکند — اپلیکیشن موبایل خودتان، پیمانکار دیگر، یا مشتری سازمانی — مستندات آن سرویس بخشی از محصول است، نه کار جانبی.
و معیار سنجشش ساده است: آیا یک توسعهدهنده میتواند بدون پرسیدن از شما، اولین درخواست موفقش را بفرستد؟
اگر جواب نه است، مستند شما ناقص است هرقدر هم بلند باشد.
قاعدهٔ اول: تولید کنید، ننویسید
مستند دستینوشته همیشه از کد عقب میافتد. این قانون است، نه احتمال.
بخشی که باید از خود کد یا از تعریف OpenAPI تولید شود: فهرست نقاط انتهایی، پارامترها، ساختار پاسخ، کدهای وضعیت.
آنچه باید دستی نوشته شود — و همانجایی است که ارزش واقعی است:
- مقدمه و شروع سریع
- نحوهٔ احراز هویت
- نمونههای کارکردنی
- رفتار در حالت خطا
- محدودیتها و قواعد کسبوکاری
این تفکیک همان اصلی است که در مستندسازی نرمافزار گفتیم: هر چیزی که از کد قابل استخراج است، ننویسید.
آنچه واقعاً لازم است
شروع سریع
اولین صفحه باید در کمتر از پنج دقیقه به اولین درخواست موفق برساند: چطور کلید بگیرم، اولین درخواست چیست، پاسخ موفق چه شکلی است.
نه معماری، نه فلسفه، نه فهرست کامل امکانات. یک مسیر کوتاه تا موفقیت اول.
نمونههای واقعی
نمونهای که کپی و اجرا شود. با دستور خط فرمان، و ترجیحاً در یکی دو زبان رایج.
پاسخ واقعی، نه شماتیک. { "id": 1, "name": "string" } کمکی نمیکند.
پاسخ کامل با دادههای واقعینما کمک میکند.
و برای مصرفکنندهٔ ایرانی، نمونهها باید فارسی داشته باشند — نام فارسی،
تاریخ شمسی اگر پشتیبانی میکنید، شمارهٔ موبایل ایرانی. مصرفکننده باید ببیند
که سرویس با دادهٔ واقعی او چطور رفتار میکند، نه با John Doe.
رفتار خطا — مهمترین بخش
اینجا تقریباً همهٔ مستندات ناقصاند.
هر کسی که با سرویس بیرونی کار کرده میداند سختترین بخش، فهمیدن این است که وقتی چیزی اشتباه پیش میرود، دقیقاً چه برمیگردد.
آنچه باید مستند شود:
- فهرست کامل خطاها با کد و معنی.
- ساختار ثابت پاسخ خطا. یک قالب برای همه، نه هر نقطه یک شکل.
- قابل تفکیک بودن خطای کاربر از خطای سرور. مصرفکننده باید بداند تلاش مجدد فایده دارد یا نه.
- خطای اعتبارسنجی، به تفکیک فیلد.
محدودیتها
- محدودیت نرخ: چند درخواست در چه بازهای، و چه پاسخی میگیرید اگر رد شوید. و سرصفحهای که میگوید چقدر باقی مانده — بدون آن، مصرفکننده فقط میتواند حدس بزند.
- حداکثر اندازهٔ درخواست و پاسخ.
- مهلت زمانی.
- صفحهبندی: روشش چیست و حداکثر تعداد در هر صفحه چقدر است.
نسخهبندی
- نسخهٔ فعلی چیست و چطور مشخص میشود.
- سیاست تغییرات ناسازگار: چقدر از قبل اطلاع میدهید؟
- نسخهٔ قدیمی تا کِی پشتیبانی میشود؟
این بند برای اپلیکیشن موبایل حیاتی است، چون نمیتوانید همهٔ کاربران را به نسخهٔ جدید ببرید — همان مسئلهای که در انتشار اپلیکیشن گفتیم.
محیط آزمایش
ارزشمندترین چیزی که میتوانید بدهید و کمتر از همه داده میشود.
مصرفکننده باید بتواند بدون دادهٔ واقعی و بدون ترس، سرویس را امتحان کند:
- کلید آزمایشی که بهسادگی صادر شود.
- دادهٔ نمونهٔ ثابت که با آن بشود تست نوشت.
- راهی برای شبیهسازی خطاها. مثلاً شناسهای که همیشه خطای «موجودی ناکافی» برمیگرداند. بدون این، مصرفکننده نمیتواند مسیر خطا را تست کند — و همان مسیر است که در تولید میشکند.
آنچه فراتر از مستندات لازم است
رویدادهای برگشتی (webhook)، اگر دارید: فهرست رویدادها، ساختار پیام، نحوهٔ تأیید اصالت، و سیاست تلاش مجدد. و صریح بگویید که تحویل «حداقل یک بار» است — یعنی مصرفکننده باید تکرار را خودش خنثی کند، با همان منطقی که در کارهای پسزمینه گفتیم.
صفحهٔ وضعیت سرویس. آیا الان بالاست؟ سابقهٔ قطعیها؟
تاریخچهٔ تغییرات، بهترتیب زمانی. مصرفکنندهای که برمیگردد باید بفهمد از آخرین بار چه عوض شده.
راه ارتباط. وقتی چیزی کار نمیکند، به کجا پیام بدهند؟
آزمون کیفیت
سه سؤال:
۱. کسی که تا حالا سرویس را ندیده، در چه مدت اولین درخواست موفقش را میفرستد؟ بیش از پانزده دقیقه یعنی مشکل دارید.
۲. کدام سؤالها بیشتر از شما پرسیده میشوند؟ هر سؤال تکراری، شکافی در مستندات است. فهرست این سؤالها، بهترین نقشهٔ راه بهبود مستندات است.
۳. آیا مستند با نسخهٔ فعلی میخواند؟ یک نمونه را کپی کنید و اجرا کنید. اگر کار نکرد، مستند شما بیاعتبار است.
آن آزمون سوم را در خط لولهٔ CI/CD خودکار کنید: تستی که نمونههای مستندات را اجرا میکند. این تنها راهی است که مستند از کد عقب نیفتد بدون اینکه کسی به نظمش تکیه کند.
و برای سرویس داخلی
اگر سرویستان فقط داخل سازمان مصرف میشود، همهٔ اینها لازم نیست — ولی این سه لازم است:
تعریف OpenAPI، که خودکار تولید شود.
نمونهٔ درخواست و پاسخ واقعی.
رفتار خطا، با همان تأکیدی که بالا گفتیم.
تیم داخلی هم همان مشکل تیم بیرونی را دارد: تا وقتی نبیند در حالت خطا چه برمیگردد، کدی مینویسد که فقط در مسیر موفق کار میکند.