API آماده چیست و از کجا بگیریم؟ راهنمای انتخاب و راه‌اندازی

API آماده یعنی به‌جای اینکه بک‌اند را از صفر بنویسید، مجموعه‌ای از اندپوینت‌های کارکننده تحویل بگیرید و همان روز اول به آن وصل شوید. مشکل اینجاست که چهار چیز کاملاً متفاوت زیر همین یک اسم فروخته می‌شود، و انتخاب اشتباه یعنی سه ماه بعد فهمیدن اینکه چیزی که گرفته‌اید اصلاً بک‌اند نبوده است. این راهنما آن چهار نوع را از هم جدا می‌کند، معیارهای انتخاب را می‌دهد و مسیر عملی راه‌اندازی را نشان می‌دهد.

API آماده دقیقاً یعنی چه؟

API قراردادی است بین کد شما و جایی که داده نگه‌داری می‌شود: آدرس‌هایی که با آن‌ها رکورد می‌سازید، می‌خوانید، ویرایش می‌کنید و حذف می‌کنید. در مسیر معمول، این آدرس‌ها را کسی می‌نویسد — با یک زبان سمت سرور، روی یک دیتابیس، و روی سروری که باید نگه‌داری شود.

«آماده» یعنی این مرحله حذف شده. شما می‌گویید داده‌تان چه شکلی است و اندپوینت‌ها موجودند. اما «موجود بودن اندپوینت» به‌تنهایی چیز زیادی نمی‌گوید: یک فایل JSON استاتیک روی CDN هم اندپوینت دارد. سؤال درست این است که پشت آن اندپوینت چه چیزی ایستاده.

چهار چیزی که همه‌شان «API آماده» صدا زده می‌شوند

۱. API عمومی داده (Public Data API). سرویس‌هایی که داده‌ی خودشان را می‌دهند: نرخ ارز، آب‌وهوا، استعلام کد پستی، تقویم شمسی. اینجا داده مال آن‌هاست و شما فقط می‌خوانید. برای بک‌اند محصول شما بی‌فایده است — چون داده‌ی کاربران شما در آن نوشته نمی‌شود.

۲. بویلرپلیت و قالب کد. یک ریپازیتوری آماده که CRUD و لاگین را از قبل نوشته. کد مال شماست، پس آزادی کامل دارید — ولی از لحظه‌ی git clone نگه‌داری هم مال شماست: وابستگی‌ها، مهاجرت دیتابیس، دیپلوی، بکاپ. این را در کدنویسی آماده مفصل باز کرده‌ایم.

۳. Mock API. اندپوینت‌هایی که جواب ساختگی می‌دهند تا فرانت‌اند بتواند جلو برود. برای دموی طراحی عالی‌اند و برای محصول واقعی هیچ. داده‌ای ذخیره نمی‌شود.

۴. پلتفرم بک‌اند (BaaS). دیتابیس واقعی، اندپوینت‌های خودکار روی مدل داده‌ی خودتان، احراز هویت، مستندات و کلید — به‌شکل سرویس. تنها گزینه‌ای از این چهار تا که واقعاً جای بک‌اند را می‌گیرد. فیکارو در همین دسته است.

API آماده در برابر API دست‌ساز

فرض کنید یک اپ رزرو نوبت می‌سازید. مدل داده‌اش سه موجودیت دارد: کاربر، خدمت، نوبت. مسیر دست‌ساز یعنی انتخاب فریم‌ورک، طراحی جدول‌ها، نوشتن لایه‌ی دسترسی به داده، نوشتن اعتبارسنجی، نوشتن لاگین، نوشتن مستندات (که معمولاً نوشته نمی‌شود)، اجاره‌ی سرور، تنظیم SSL، راه‌اندازی بکاپ، و بعد نگه‌داری همه‌ی این‌ها تا آخر عمر محصول.

هیچ‌کدام از این کارها اختصاصی محصول شما نیست. چیزی که واقعاً اختصاصی است — اینکه «نوبت» چه فیلدهایی دارد و چه قاعده‌ای بر آن حاکم است — کمترین بخش زمان را می‌گیرد. API آماده دقیقاً همین نسبت را برعکس می‌کند: تمام وقت‌تان صرف مدل داده و قواعد می‌شود.

نکته‌ی صادقانه: API دست‌ساز یک برتری واقعی دارد و آن کنترل کامل است. اگر معماری‌تان چیز غیرمعمولی می‌خواهد — صف پیام سنگین، پردازش ویدیو، الگوریتم اختصاصی — بخشی از کار همچنان کد اختصاصی می‌خواهد. تفاوت این است که آن بخش را می‌نویسید، نه کل CRUD را.

چک‌لیست انتخاب یک API آماده

قبل از انتخاب، این هفت مورد را بپرسید. هر «نه» یک بدهی آینده است:

1. پشت اندپوینت دیتابیس واقعی هست؟ اسپردشیت و فایل JSON نه تراکنش دارند، نه رابطه، نه ایندکس. برای دمو خوب‌اند و برای محصول، دیوار.
2. مدل داده قابل تغییر است، بی‌آنکه سرویس بخوابد؟ اضافه کردن یک فیلد نباید یعنی مهاجرت دستی و دیپلوی مجدد.
3. فیلتر، مرتب‌سازی و صفحه‌بندی داخل خود API هست؟ بدون این‌ها، اولین لیستِ هزارتایی کلاینت را زمین می‌زند. (مستندات کار با API)
4. احراز هویت کاربر نهایی دارد؟ فرق است بین «کلید برنامه» و «حساب کاربر». اگر اپ‌تان ثبت‌نام دارد، به هر دو نیاز دارید.
5. مستندات خودکار به‌روز می‌ماند؟ Swagger و کالکشن Postman که خودشان با تغییر مدل داده به‌روز می‌شوند، در عمل تفاوت بین «سریع وصل شدم» و «دو روز حدس زدم» است.
6. پرداخت و دسترسی برای تیم داخل ایران دردسر ندارد؟ پرداخت ارزی یعنی واسطه و ریسک مسدودی حساب — با داده‌تان داخلش.
7. خروجی کامل داده می‌دهد؟ سرویسی که در خروج را باز نمی‌گذارد، دارد شما را قفل می‌کند. (خروجی‌ها و SDK)

راه‌اندازی یک API آماده در عمل

مسیر واقعی در فیکارو چهار قدم است — نسخه‌ی مفصل در شروع سریع:

قدم ۱ — پروژه. بعد از ثبت‌نام رایگان یک پروژه بسازید. هر پروژه آدرس اختصاصی خودش را می‌گیرد:

https://api.fikaro.ir/{slug}/v1/{entity}

قدم ۲ — مدل داده. موجودیت‌ها و فیلدها را تعریف کنید: appointment با تاریخ، وضعیت و رابطه به user. انواع فیلد آماده‌اند — متن، عدد، تاریخ، ایمیل، موبایل، فایل و رابطه. (مستندات مدل داده)

قدم ۳ — اعمال. پیش‌نمایش تغییرات را می‌بینید و بعد از تأیید، اندپوینت‌ها همان لحظه فعال‌اند. بدون build، بدون deploy.

قدم ۴ — اولین درخواست.

curl "https://api.fikaro.ir/my-clinic/v1/appointment?filter[status]=pending&sort=-created_at&limit=20" \
  -H "Authorization: Bearer apck_..."

{
  "data": [
    { "id": "0192f3...", "status": "pending", "created_at": "2026-08-05T09:12:44Z" }
  ],
  "pagination": { "limit": 20, "nextCursor": "eyJ..." }
}

فیلتر، مرتب‌سازی و صفحه‌بندی مبتنی بر cursor از همان اول در دسترس‌اند؛ چیزی برایشان ننوشته‌اید.

هزینه‌ی API آماده را چطور بسنجیم؟

مقایسه‌ی درست، «قیمت سرویس در برابر صفر» نیست؛ «قیمت سرویس در برابر هزینه‌ی واقعی ساخت و نگه‌داری» است. طرف دوم شامل حقوق توسعه‌دهنده‌ی بک‌اند، اجاره‌ی سرور، زمان دیپلوی، و آن شبی است که سرویس می‌خوابد و کسی باید بیدار شود.

در فیکارو مدل هزینه ساعتی و از کیف‌پول است — نه اشتراک ماهانه، نه پیش‌پرداخت. پروژه‌ی متوقف هزینه‌ای ندارد و صفحه‌ی قیمت‌گذاری نشان می‌دهد هر مبلغ شارژ چند روز پروژه را روشن نگه می‌دارد.

کجا API آماده کافی نیست؟

سه مرز را باید از اول بدانید:

• منطق تجاری پیچیده. اعتبارسنجی و قواعد معمول («سفارش زیر صفر رد شود»، «مبلغ کل خودکار حساب شود») با موتور قوانین و بدون کد ساخته می‌شوند و قبل از اعمال Dry Run دارند. برای چیزی که یک شرط ساده نیست — مثلاً استعلام از یک سرویس بیرونی وسط ثبت سفارش — یک لایه‌ی جاوااسکریپت داخل پنل و همچنین وبهوک وجود دارد؛ وبهوک چطور کار می‌کند را جدا نوشته‌ایم.
• فرانت‌اند کار خودتان است. API آماده بک‌اند می‌دهد؛ رابط کاربری اپ یا سایت را شما می‌سازید.
• بار و معماری غیرمعمول. پردازش سنگین، جریان‌های بلادرنگ حجیم و الگوریتم اختصاصی، سرویس اختصاصی خودشان را می‌خواهند.

اگر می‌خواهید گزینه‌ها را کنار هم ببینید، Backend as a Service ایرانی مقایسه‌ی Firebase و Supabase با گزینه‌ی داخلی را دارد؛ و اگر از سمت اپ موبایل می‌آیید، بک‌اند فلاتر و ری‌اکت‌نیتیو مسیر اتصال را قدم‌به‌قدم نشان می‌دهد.

سوالات متداول

فرق API آماده با وب سرویس چیست؟

«وب سرویس» اصطلاح عمومی‌تری است برای هر سرویسی که از طریق شبکه فراخوانی می‌شود و شامل SOAP هم می‌شود؛ API آماده یعنی همان وب سرویس، ولی از قبل ساخته‌شده و آماده‌ی مصرف. تفاوت‌های فنی را در مقاله REST API و وب سرویس باز کرده‌ایم.

آیا API آماده رایگان هم وجود دارد؟

API عمومی داده معمولاً سطح رایگان دارد چون فقط خواندنی است. پلتفرم بک‌اند هزینه دارد، ولی معمولاً با اعتبار اولیه شروع می‌شود. در فیکارو با ثبت‌نام اعتبار هدیه می‌گیرید و بدون پرداخت شروع می‌کنید.

با API آماده چقدر سریع به اولین درخواست می‌رسم؟

اگر مدل داده‌تان را از قبل می‌دانید، در حد یک نشست کاری. تعریف موجودیت‌ها و اعمال تغییرات چند دقیقه است و بعد از آن اندپوینت‌ها همان لحظه فعال‌اند؛ زمان واقعی صرف تصمیم درباره مدل داده می‌شود، نه راه‌اندازی.

اگر پروژه بزرگ شد، از API آماده به بک‌اند اختصاصی می‌شود مهاجرت کرد؟

بله، به شرطی که سرویس خروجی کامل بدهد. در فیکارو مدل داده، رکوردها و قوانین یک‌جا قابل خروجی گرفتن‌اند و تیم جدید روی هر زیرساختی ادامه می‌دهد.