ساخت REST API با پایتون

اولین REST APIی که با پایتون نوشتم، یک اسکریپت Flask بود که همه endpointها را در یک فایل جا داده بود. بعد از دو ماه، همان فایل به سیصد خط رسید و هر تغییر کوچک، ریسک شکستن بخش دیگری از API را داشت. آن روز یاد گرفتم که ساخت API با پایتون بیش از آنکه به دانستن سینتکس وابسته باشد، به انتخاب فریم‌ورک مناسب و معماری درست نیاز دارد. اگر با مفهوم کلی API آشنا نیستید، API چیست نقطه شروع خوبی است.

انتخاب فریم‌ورک: Django REST یا Flask؟

در پایتون، دو انتخاب اصلی برای ساخت REST API وجود دارد: Django REST Framework (DRF) و Flask. انتخاب بین این دو، اولین تصمیم بزرگ پروژه است و تعیین می‌کند در چند ماه آینده چه سطحی از انعطاف و چه مقدار کد آماده در اختیار خواهید داشت. اگر با جنگو آشنا نیستید، بک‌اند چیست و چه وظایفی دارد نقطه شروع خوبی است و راهنمای کامل Django برای بک‌اند تحلیل عمیق‌تری ارائه می‌دهد.

انتخاب من در پروژه‌ها معمولاً به این شکل است: اگر پروژه پایگاه داده رابطه‌ای پیچیده دارد، نیاز به پنل مدیریت دارد و چند توسعه‌دهنده روی آن کار می‌کنند، Django REST Framework انتخاب اول است. اگر پروژه میکروسرویس است، فقط چند endpoint دارد و سبک بودن مهم است، Flask انتخاب بهتری است. برای آشنایی عملی با Flask، Flask سبک و انعطاف‌پذیر و آموزش فلسک در پایتون نقطه شروع خوبی است.

انتخاب فریم‌ورک، انتخاب معماری نیست؛ انتخاب سرعت شروع و سرعت تغییر در آینده است. کدام برای شما مهم‌تر است، تصمیم را روشن می‌کند.

ساختار پروژه API در پایتون

در Django، ساختار پروژه از ابتدا تعریف شده است: هر اپلیکیشن یک پوشه، هر مدل یک فایل، هر view یک فایل. این ساختار در پروژه‌های بزرگ، نظم را حفظ می‌کند. در Flask، ساختار پروژه را خودتان می‌سازید و این آزادی هم فرصت است و هم خطر. در پروژه‌های Flask که با آن‌ها کار کرده‌ام، ساختاری که به آن رسیده‌ام شامل سه پوشه اصلی است: app برای کد، tests برای تست‌ها و migrations برای تغییرات دیتابیس. هر endpoint یک فایل جداگانه در پوشه routes دارد که با Blueprint به اپلیکیشن اصلی وصل می‌شود.

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

طراحی مسیرها و endpointها

طراحی endpointها، مستقیماً بر تجربه مصرف‌کنندگان API اثر می‌گذارد. اصول REST می‌گوید هر منبع یک URL دارد و متدهای HTTP، عملیات را تعیین می‌کنند. اگر با اصول طراحی REST آشنا نیستید، اصول طراحی REST API و REST از پایه تا طراحی حرفه‌ای راهنمای کاملی دارند. برای مفاهیم ابتدایی هم REST API چیست پیش‌نیاز خوبی است.

در Django REST Framework، ViewSetها این کار را ساده می‌کنند. یک ViewSet می‌تواند هم لیست را برگرداند، هم جزئیات را، هم بسازد و هم به‌روز کند. Routerها به صورت خودکار این ViewSetها را به URLها وصل می‌کنند. این الگو، کد را کمتر و خواناتر می‌کند. در Flask، معمولاً هر endpoint به صورت دستی با @app.route تعریف می‌شود که انعطاف بیشتر اما کد بیشتری می‌طلبد.

یک نکته عملی در طراحی endpoint: از ابتدا برای صفحه‌بندی فکر کنید. حتی اگر امروز دیتای کمی دارید، فردا ممکن است هزاران ردیف داشته باشید. پارامترهایی مثل page و per_page یا استفاده از cursor-based pagination، از ابتدا باید در طرح شما باشد. اضافه کردن این قابلیت بعد از اینکه API در production است، ریسک ناسازگاری دارد.

سریال‌سازی داده و فرمت JSON

سریال‌سازی یعنی تبدیل اشیاء پایتون به JSON که قابل انتقال روی شبکه است. اگر با ساختار JSON آشنا نیستید، JSON چیست و چگونه داده‌ها را ساختاردهی می‌کند پیش‌نیاز مفیدی است و کار با JSON در پروژه‌های واقعی نکات کاربردی دارد. در Django REST Framework، Serializerها این کار را به صورت خودکار و با اعتبارسنجی یکپارچه انجام می‌دهند. هر سریالایزر هم می‌تواند برای خواندن استفاده شود و هم برای نوشتن.

در Flask، سریال‌سازی معمولاً با کتابخانه Marshmallow یا Pydantic انجام می‌شود. هر دو ابزار عالی هستند اما Pydantic به دلیل محبوبیت در FastAPI و تایپ‌های صریح، انتخاب محبوب‌تری در پروژه‌های جدید است. یک مزیت Marshmallow، اعتبارسنجی داخلی قوی است که برای فرم‌های پیچیده بسیار مفید است. برای ساختار استاندارد پاسخ API در پایتون، الگوی سه بخشی status، data و errors که در REST API توصیه می‌شود، به کار می‌رود.

احراز هویت و مدیریت کاربران

در Django REST Framework، سیستم احراز هویت به صورت پیش‌فرض با session و Basic Auth فعال است. برای APIهای واقعی، TokenAuthentication یا JWT توصیه می‌شود. برای آشنایی با JWT، JWT چیست و چه کاربردی در احراز هویت دارد و برای درک کامل روش‌های مختلف، احراز هویت در API و OAuth چیست و چگونه کار می‌کند را ببینید.

در Flask، احراز هویت معمولاً با افزونه‌هایی مثل Flask-JWT-Extended انجام می‌شود. این افزونه هم JWT را در سطح production پشتیبانی می‌کند. یک نکته مهم: در هر دو فریم‌ورک، توکن‌ها باید در header به شکل Authorization: Bearer <token> ارسال شوند نه در URL. ارسال توکن در URL باعث می‌شود در لاگ سرور و history مرورگر ذخیره شود.

مدیریت نقش‌ها و دسترسی‌ها در پایتون معمولاً با decorator انجام می‌شود. در DRF، permission_classes روی هر view تعیین می‌شود. در Flask، decoratorهای سفارشی که قبل از اجرای view، نقش کاربر را چک می‌کنند. این الگو در پروژه‌های بزرگ بسیار کارآمد است چون تمام دسترسی‌ها در یک لایه بررسی می‌شوند. برای مدیریت امن رمزهای عبور، اصول مدیریت رمز عبور امن راهنمای کاملی دارد.

اتصال به دیتابیس و ORM

Django ORM یک لایه انتزاعی است که کار با دیتابیس را ساده می‌کند. برای پروژه‌هایی که دیتابیس رابطه‌ای استاندارد دارند، این ابزار کافی است. برای پروژه‌هایی که کوئری‌های پیچیده با joinهای زیاد دارند، باید به SQL خام پناه برد. برای آشنایی با SQL و کوئری‌های حرفه‌ای، SQL از صفر تا کوئری‌های حرفه‌ای نقطه شروع خوبی است.

در Flask، انتخاب ORM آزاد است. SQLAlchemy رایج‌ترین انتخاب است و در پروژه‌هایی که به ORM پیچیده نیاز دارند، ابزار قدرتمندی است. برای مدیریت مهاجرت‌های دیتابیس، Alembic در Flask و migrationهای داخلی Django در DRF استاندارد هستند. مدیریت مهاجرت در پروژه‌های بزرگ، یکی از چالش‌های جدی است چون هر تغییر در ساختار جدول، ممکن است به داده‌های موجود آسیب بزند. الگوی امن این است که قبل از هر migration، یک بکاپ کامل بگیرید و روی محیط staging تست کنید.

برای اتصال به MySQL که رایج‌ترین دیتابیس در پروژه‌های پایتونی است، اتصال پایتون به MySQL راهنمای کاملی دارد. برای طراحی دیتابیس استاندارد، طراحی دیتابیس در MySQL نکات مهمی ارائه می‌دهد.

ORM سرعت توسعه را بالا می‌برد اما اگر به جای آن فکر نکنید، عملکرد را پایین می‌آورد. همیشه بدانید ORM شما زیر کاپوت چه کوئری‌ای می‌زند.

نکات امنیتی در API پایتون

امنیت API، مجموعه‌ای از تصمیم‌های کوچک است. چند مورد که در پروژه‌ها نجات‌دهنده بودند:

• محدودسازی نرخ درخواست: با ابزارهایی مثل django-ratelimit یا Flask-Limiter.
• HTTPS اجباری: همه درخواست‌های HTTP باید به HTTPS ریدایرکت شوند.
• اعتبارسنجی ورودی: هر ورودی باید اعتبارسنجی و پاک‌سازی شود.
• پاک‌سازی خروجی: داده حساس نباید در پاسخ‌ها افشا شود.
• لاگ کامل: هر درخواست با جزئیات ثبت شود تا در صورت حمله قابل تحلیل باشد.
• هدرهای امنیتی: با استفاده از django-csp یا flask-talisman پیکربندی شوند.

راهنمای کامل اصول امنیتی در امنیت API و بهترین روش‌ها و چگونه REST API امن بسازیم آمده است. برای درک تهدیدهای رایج، حملات XSS، SQL Injection و CSRF را ببینید. برای هدرهای امنیتی هم هدرهای امنیتی HTTP راهنمای کاملی دارد. و اگر احراز هویت دو مرحله‌ای می‌خواهید، فعال‌سازی 2FA ایده‌های مفیدی می‌دهد.

یک نکته عملی که در پروژه‌ها به آن رسیدم: هرگز کلیدهای سری مثل SECRET_KEY، کلیدهای API و اطلاعات اتصال دیتابیس را در کد ذخیره نکنید. از متغیرهای محیطی استفاده کنید و مطمئن شوید فایل حاوی آن‌ها در .gitignore قرار دارد. این یک قاعده ساده است اما بیش از هر چیز دیگری در پیشگیری از افشای اطلاعات نقش دارد.

پرسش‌های پرتکرار درباره API پایتون

آیا Django REST یا Flask سریع‌تر است؟ Flask در پاسخ‌های ساده سریع‌تر است چون overhead کمتری دارد. اما در پروژه‌های پیچیده با قابلیت‌های زیاد، Django REST با ابزارهای آماده‌اش می‌تواند سریع‌تر عمل کند. تفاوت در سناریوهای واقعی معمولاً ناچیز است.

چگونه API پایتون را در production اجرا کنم؟ در Django، با Gunicorn و Nginx. در Flask هم با Gunicorn و Nginx. هرگز از سرور توسعه داخلی پایتون برای production استفاده نکنید چون امن و پایدار نیست.

چگونه نسخه‌بندی API را مدیریت کنم؟ در Django REST Framework، Versioning داخلی وجود دارد و می‌توانید از URL-based versioning استفاده کنید. جزئیات در نسخه‌بندی REST API آمده است.

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

چگونه API را تست کنم؟ با Postman برای تست دستی و pytest برای تست خودکار. راهنمای کار با Postman در تست REST API با Postman و تست API آمده است.

برای آشنایی با ساختار پروژه‌های وردپرسی که با پایتون تعامل دارند، استفاده از REST API در وردپرس و REST API در وردپرس را ببینید. برای مبانی جنگو، Django برای پروژه‌های پایتونی و برای ساخت اپلیکیشن وب، ساخت اپلیکیشن وب با Flask راهنمای مفیدی است. اگر روی داده‌های حساس کار می‌کنید، کار با آرایه‌ها در برنامه‌نویسی و کار با آرایه‌ها در پایتون پیش‌نیازهای مفیدی هستند.

آنچه از پروژه‌های واقعی یاد گرفتم

سه چیز بعد از سال‌ها کار با API در پایتون یاد گرفتم. اول، انتخاب فریم‌ورک بر اساس نیاز واقعی پروژه، نه محبوبیت لحظه‌ای. دوم، ساختار و معماری را جدی بگیرید چون هزینه تغییر بعدی بالاست. سوم، امنیت را از روز اول بگنجانید نه به عنوان افزودنی. برای آشنایی با ابزارهای مقایسه‌ای، تفاوت REST و GraphQL و ساخت REST API با پایتون (نسخه جامع‌تر) را ببینید. برای مستندسازی، مستندسازی API و برای اشتباهات رایج، اشتباهات رایج REST API راهنمای مفیدی است. برای درک اصول طراحی، REST API در عمل تحلیل عمیقی دارد.

اگر تجربه‌ای از ساخت REST API با پایتون در پروژه‌ای واقعی دارید - چه موفق چه با چالش‌ها - در دیدگاه بنویسید. برای من جالب است بدانم کدام فریم‌ورک را انتخاب کرده‌اید و کدام بخش از ساخت پروژه، بیشترین زمان تیم شما را گرفته است. 🐍