مفاهیم پایه

پنج مفهوم، کل فیکارو را توضیح می‌دهند. اگر همین صفحه را بخوانید، بقیهٔ مستندات فقط جزئیات است.

پروژه و نشانی (slug)

هر پروژه یک بک‌اند مستقل است: دیتابیس، API، کلیدها و مستندات خودش را دارد. نشانی پروژه (slug) در مسیر API می‌نشیند:

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

موجودیت و فیلد

موجودیت (entity) همان جدول دادهٔ شماست — مثل product یا order — و فیلد ستون‌های آن. هر دو، دو نام دارند: نام نمایشی فارسی برای پنل، و شناسهٔ انگلیسی برای API. شناسه را خودتان انتخاب می‌کنید (انگلیسی، حروف کوچک، snake_case) و بعد از انتشار بهتر است ثابت بماند تا کلاینت‌ها نشکنند.

موتور اسکیمامحور، نه تولید کد

فیکارو از روی مدل شما کد تولید نمی‌کند که بعد نیاز به build داشته باشد؛ یک موتور اجرایی، تعریف (اسکیمای) پروژه را می‌خواند و هر درخواست را همان لحظه بر اساس آن اجرا می‌کند. پیامد عملی‌اش برای شما:

• افزودن یا حذف فیلد = تغییر تعریف؛ بدون ری‌استارت و توقف سرویس.
• مستندات، Postman و SDK همیشه از روی همان تعریف ساخته می‌شوند و عقب نمی‌مانند.

اعمال تغییرات (ایمن یا مخرب)

تغییرات مدل داده تا وقتی «ذخیره و اعمال» نزنید روی API اثر ندارند. موقع اعمال، فیکارو تغییرات را تحلیل می‌کند:

• ایمن — مثل افزودن موجودیت یا فیلد اختیاری؛ بی‌خطر اعمال می‌شود.
• هشدار — مثل افزودن فیلد الزامی یا قید یکتا.
• مخرب — مثل حذف فیلد یا تغییر نوع؛ تأیید صریح می‌خواهد.

هر اعمال در «تغییرات» (Changelog) پروژه ثبت می‌شود.

دو نوع کلید

• Playground — برای آزمایش؛ سقف نرخ محدود، مناسب مستندات و پنل آزمایش زنده.
• Production — برای محیط واقعی؛ هش‌شده نگهداری می‌شود و فقط یک بار نمایش داده می‌شود.

جزئیات در کلیدها و احراز هویت.