وقتی کارفرما می‌گوید «یک API برای اپ موبایلمان می‌خواهیم»، معمولاً منظورش فهرست صفحه‌های اپ است. اما API قراردادی است که چند مصرف‌کننده، سال‌ها به آن وابسته می‌مانند. تصمیم‌هایی که در شروع گرفته نمی‌شوند، بعداً به نسخههای ناسازگار، اپ‌هایی که بعد از به‌روزرسانی سرور از کار می‌افتند و هزینه‌های غیرمنتظره تبدیل می‌شوند. این چک‌لیست نیازمندی پروژه API برای کارفرما سؤال‌هایی است که پیش از برآورد و قرارداد باید جوابشان روشن باشد؛ حتی اگر جواب «هنوز نمی‌دانیم» باشد.
چک‌لیست عمومی شروع پروژه را در مقاله چک‌لیست شروع پروژه Laravel نوشته‌ام. این مقاله فقط روی موارد خاص API تمرکز دارد. جنبه فنی پیاده‌سازی هم در طراحی REST API در Laravel آمده است.
۱. مصرفکنندهها چه کسانی هستند؟
اولین و مهم‌ترین سؤال. پاسخ آن روی امنیت، نسخه‌بندی و مستندات اثر مستقیم دارد.
- فقط اپ‌های خود شما (وب، اندروید، iOS)؟ یا شرکای تجاری و توسعه‌دهندگان بیرونی هم به آن وصل می‌شوند؟ API عمومی مستندات، کلید دسترسی، محدودیت نرخ و سیاست تغییر جدی‌تری لازم دارد.
- اپ موبایل؟ اگر بله، نسخههای قدیمی اپ روی گوشی کاربران ماه‌ها باقی می‌مانند. API باید با چند نسخه اپ همزمان سازگار باشد و برای اجبار به به‌روزرسانی سازوکاری داشته باشد.
- سیستم‌های داخلی مثل حسابداری، انبار یا CRM هم داده می‌خوانند یا می‌نویسند؟ این اتصال‌ها معمولاً به همگام‌سازی، صف و webhook نیاز دارند.
۲. هویت و دسترسی
- کاربران چطور وارد می‌شوند؟ رمز عبور، کد یکبارمصرف پیامکی، ورود با حساب گوگل، یا ترکیبی از این‌ها؟
- چه نقش‌هایی وجود دارد و هر نقش به چه داده‌ای دسترسی دارد؟ یک جدول ساده «نقش × عملیات» قبل از شروع، جلوی بخش بزرگی از حفره‌های امنیتی را می‌گیرد.
- آیا یک کاربر می‌تواند در چند سازمان یا فروشگاه عضو باشد؟ این سؤال در ظاهر کوچک است اما مدل داده را کاملاً تغییر می‌دهد.
- نشست چقدر معتبر است؟ خروج از همه دستگاه‌ها لازم است؟ با گم‌شدن گوشی چه اتفاقی باید بیفتد؟
- برای سرویسهای ماشین‌به‌ماشین، کلید API یا توکن جداگانه لازم است؟
۳. قرارداد داده
برای هر بخش اصلی محصول، بدون ورود به جزئیات فنی، این‌ها را مشخص کنید:
- موجودیتهای اصلی و ارتباطشان: کاربر، سفارش، محصول، پرداخت و غیره.
- کدام داده‌ها قابل ویرایش‌اند و چه کسی می‌تواند ویرایش کند؟ تاریخچه تغییرات لازم است؟
- داده حساس کدام است؟ کد ملی، شماره کارت، آدرس، اطلاعات پزشکی. این داده‌ها نیاز به محدودیت دسترسی، لاگ و گاهی رمزنگاری دارند.
- حجم تقریبی: چند کاربر، چند سفارش در روز، چند فایل؟ عدد دقیق لازم نیست؛ مرتبه بزرگی کافی است. صد سفارش در روز با صد هزار سفارش طراحی متفاوتی دارد.
- زبان و تقویم: تاریخ شمسی فقط در نمایش است یا در منطق کسب‌وکار هم استفاده می‌شود؟ اعداد فارسی، جهت متن و جستجوی فارسی چطور؟
۴. رفتار در شرایط غیرعادی
اکثر برآوردهای اشتباه از نادیده گرفتن همین بخش است. API باید برای این موقعیت‌ها رفتار مشخصی داشته باشد:
- کاربر دو بار روی «پرداخت» می‌زند یا شبکه موبایل درخواست را دو بار می‌فرستد. سفارش تکراری ساخته شود یا نه؟
- درگاه پرداخت پول را کسر می‌کند اما بازگشت به سایت انجام نمی‌شود. سفارش در چه وضعیتی می‌ماند و چه کسی آن را اصلاح می‌کند؟
- سرویس پیامک یا انبار بیرونی در دسترس نیست. کاربر خطا ببیند یا کار در صف بماند و بعداً انجام شود؟
- کاربر در حالت آفلاین چیزی ثبت می‌کند. اپ باید بعداً همگام‌سازی کند؟ تعارض‌ها چطور حل شوند؟
جواب این سؤال‌ها تعیین می‌کند چقدر به صف، idempotency و webhook نیاز دارید. اگر پروژه شما به سرویسهای بیرونی وصل می‌شود، مقاله Resilient Third-Party API Integrations in Laravel الگوهای اصلی را توضیح می‌دهد.
۵. کارایی و دسترس‌پذیری
- چه زمان پاسخی قابل قبول است؟ برای اکثر عملیات‌ها عددی مثل «زیر ۳۰۰ میلی‌ثانیه برای ۹۵٪ درخواست‌ها» هدف معقولی است. عملیات‌هایی که ذاتاً کندند (گزارش، خروجی Excel) باید غیرهمزمان باشند.
- ترافیک یکنواخت است یا اوج دارد؟ فروش ویژه، پخش زنده یا ارسال اعلان به همه کاربران، بار لحظه‌ای چندبرابری می‌سازد.
- قطعی چقدر قابل تحمل است؟ چند دقیقه در ماه یا چند ساعت؟ این عدد تعیین می‌کند به چند سرور، پشتیبان‌گیری و مانیتورینگ نیاز دارید و هزینه زیرساخت چقدر است.
- داده در صورت خرابی تا چه زمانی باید قابل بازیابی باشد؟ از دست دادن یک روز داده قابل قبول است یا یک ساعت؟
۶. نسخه‌بندی و تغییر
- وقتی API تغییر ناسازگار می‌کند، اپ‌های قدیمی چه مدت باید کار کنند؟
- آیا یک endpoint برای «حداقل نسخه پشتیبانی‌شده اپ» لازم است تا اپ‌های خیلی قدیمی کاربر را به به‌روزرسانی هدایت کنند؟
- چه کسی تغییرات را تأیید می‌کند و تیم فرانتاند یا موبایل چطور از آن‌ها مطلع می‌شود؟
۷. مستندات و محیط‌ها
- مستندات API برای چه کسی است؟ تیم داخلی، پیمانکار موبایل یا شرکای بیرونی؟ سطح جزئیات و قالب (OpenAPI، Postman یا سند متنی) را مشخص کنید.
- چند محیط لازم است؟ حداقل یک محیط آزمایشی جدا از production که تیم موبایل بتواند بدون ترس از خراب کردن داده واقعی روی آن کار کند.
- داده نمونه برای محیط آزمایشی از کجا می‌آید؟
۸. عملیات بعد از تحویل
- چه کسی سرورها را نگه می‌دارد، به‌روزرسانی امنیتی انجام می‌دهد و هنگام قطعی پاسخ می‌دهد؟
- خطاها و کندی‌ها کجا ثبت می‌شوند و چه کسی هشدار دریافت می‌کند؟
- مالکیت کد، مخزن، دامنه و حساب‌های سرویسهای بیرونی با کیست؟ این را از روز اول به نام خود ثبت کنید.
فرم یک‌صفحه‌ای برای شروع
اگر وقت ندارید همه سؤال‌ها را جواب دهید، این حداقل را قبل از جلسه اول آماده کنید:
مصرفکنندهها: وب / اندروید / iOS / شرکا / سیستم داخلی
ورود کاربران: روش‌ها و نقشها
موجودیتهای اصلی: ۵ تا ۱۰ مورد مهم‌ترین
داده حساس: کدام فیلدها
حجم تقریبی: کاربران، تراکنش روزانه، اوج
سرویسهای بیرونی: پرداخت، پیامک، انبار، ...
تحمل قطعی: مثلاً «حداکثر ۱ ساعت در ماه»
اپ قدیمی: چند ماه پشتیبانی بعد از تغییر
مستندات: برای چه کسی، در چه قالبی
نگهداری: چه کسی بعد از تحویلسؤالهایی که از توسعه‌دهنده API بپرسید
چک‌لیست بالا کار شما به‌عنوان کارفرماست. اما پاسخ توسعه‌دهنده یا تیم به چند سؤال ساده هم نشان می‌دهد این تصمیم‌ها را جدی می‌گیرد یا نه:
- اگر کاربر یک درخواست پرداخت را دو بار بفرستد، API چه می‌کند؟ پاسخ خوب شامل کلید idempotency یا قید یکتایی در دیتابیس است، نه «اتفاق نمی‌افتد».
- وقتی بخواهیم یک فیلد را تغییر دهیم، اپ‌های قدیمی چطور کار می‌کنند؟ پاسخ خوب یک سیاست نسخه‌بندی یا تغییرات افزایشی است.
- از کجا می‌فهمیم API کند شده یا خطا می‌دهد؟ پاسخ خوب لاگ ساختاریافته، پایش و هشدار است، نه «کاربران خبر می‌دهند».
- مستندات چه زمانی و در چه قالبی تحویل می‌شود و چه کسی آن را به‌روز نگه می‌دارد؟
- داده حساس کجا ذخیره می‌شود و چه کسانی به آن دسترسی دارند؟
پاسخ‌های مبهم به این سؤال‌ها لزوماً به معنی بی‌تجربگی نیست، اما نشان می‌دهد این موارد هنوز در برآورد دیده نشده‌اند و احتمالاً بعداً به هزینه اضافه تبدیل می‌شوند.
جمع‌بندی
کیفیت یک API بیشتر از هر چیز به تصمیم‌هایی بستگی دارد که پیش از نوشتن اولین خط کد گرفته می‌شوند: چه کسی از آن استفاده می‌کند، در شرایط غیرعادی چه رفتاری دارد و چطور تغییر می‌کند. جواب دادن به این چک‌لیست، برآورد را دقیق‌تر و ریسک‌های پرهزینه را پیش از شروع آشکار می‌کند.
اگر برای محصولتان API یا بک‌اند تازه‌ای لازم دارید و می‌خواهید نیازمندی‌ها پیش از برآورد شفاف شوند، در خدمت طراحی API و معماری بک‌اند مقیاس‌پذیر از همین چک‌لیست شروع می‌کنیم.
پرسش‌های متداول
برای سفارش API اپ موبایل حداقل چه اطلاعاتی لازم است؟
مصرفکنندهها، روش ورود و نقشها، موجودیتهای اصلی، داده حساس، حجم تقریبی، سرویسهای بیرونی و مدت پشتیبانی از نسخههای قدیمی اپ.
آیا محیط آزمایشی جدا برای API لازم است؟
بله. تیم موبایل یا فرانتاند باید بدون خطر برای داده واقعی تست کند؛ حداقل یک محیط staging جدا از production لازم است.