@import url(‘https://cdn.jsdelivr.net/gh/rastikerdar/vazirmatn@v33.003/Vazirmatn/Vazirmatn-Variable.css’);
/* Basic responsive adjustments – more detailed styles are inline */
@media (max-width: 768px) {
h1 { font-size: 2em !important; }
h2 { font-size: 1.5em !important; }
h3 { font-size: 1.2em !important; }
.content-box, .info-box, pre, table {
padding: 15px !important;
margin-bottom: 15px !important;
}
img { max-width: 100%; height: auto; }
}
@media (max-width: 480px) {
h1 { font-size: 1.8em !important; }
h2 { font-size: 1.3em !important; }
h3 { font-size: 1.1em !important; }
.content-box, .info-box, pre, table {
padding: 10px !important;
margin-bottom: 10px !important;
}
}

آموزش Django REST Framework — مقدماتی

نقشه راه یادگیری Django REST Framework

1. مفاهیم اولیه

درک API، REST، HTTP، پایتون و جنگو.

2. نصب و راه‌اندازی

نصب DRF، پیکربندی پروژه جنگو و ایجاد اولین برنامه.

3. هسته DRF

یادگیری Serializerها، Viewها، Routerها و مفاهیم درخواست/پاسخ.

4. ساخت اولین API

پیاده‌سازی یک API ساده و تست آن.

<div style=”flex: 1 1 30%; min-width: 250px; background-color: #ffffff; padding: 20px; border-radius: 8px; box-shadow: 0 2px 8px rgba

5. مباحث پیشرفته

اشاره به احراز هویت، مجوزها، Pagination و فیلترینگ.

فهرست مطالب

• مقدمه: چرا Django REST Framework؟
• Django REST Framework چیست؟
• چرا باید از DRF استفاده کنیم؟
• شروع کار: نصب و راه‌اندازی
• مفاهیم کلیدی Django REST Framework
  • Serializers: تبدیل داده‌ها
  • Views: منطق تجاری API
  • Routers: مدیریت آسان URLها
  • Request & Response: قلب ارتباطات
• ساخت اولین API با DRF (مثال عملی)
• مقایسه Django REST Framework با سایر روش‌ها
• عیب‌یابی سریع (Troubleshooting)
• سوالات متداول (FAQ)
• نتیجه‌گیری

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

Django REST Framework چیست؟

Django REST Framework یک کیت ابزار انعطاف‌پذیر و قدرتمند برای ساخت APIهای وب است که بر پایه جنگو توسعه یافته. این فریم‌ورک تمام پیچیدگی‌های مرتبط با ساخت API را مدیریت می‌کند و به شما اجازه می‌دهد تا با حداقل کدنویسی، APIهای RESTful قدرتمند و مقیاس‌پذیری بسازید.

در واقع، DRF لایه‌هایی را به جنگو اضافه می‌کند که کار با فرمت‌های داده‌ای مثل JSON و XML، احراز هویت (Authentication)، مجوزها (Permissions)، و سایر جنبه‌های کلیدی یک API مدرن را تسهیل می‌بخشد. بدون DRF، توسعه‌دهندگان باید این قابلیت‌ها را از ابتدا خودشان پیاده‌سازی می‌کردند که زمان‌بر و مستعد خطا بود.

چرا باید از DRF استفاده کنیم؟

استفاده از DRF مزایای زیادی دارد که در اینجا به چند مورد کلیدی اشاره می‌کنیم:

• سرعت توسعه بالا: با استفاده از کامپوننت‌های آماده DRF، می‌توانید API خود را در زمان بسیار کوتاهی بسازید.
• اعمال استانداردهای RESTful: DRF به شما کمک می‌کند تا APIهایی بسازید که به بهترین شکل ممکن از اصول REST پیروی می‌کنند.
• سریالایزر‌های قدرتمند: به راحتی می‌توانید داده‌های پیچیده (مانند آبجکت‌های مدل‌های جنگو) را به فرمت‌های قابل ارسال (مانند JSON) تبدیل کنید و بالعکس.
• مستندسازی خودکار: DRF به صورت داخلی رابط کاربری قابل مرور (Browsable API) را فراهم می‌کند که مستندسازی و تست API شما را آسان می‌کند.
• امنیت بالا: مکانیزم‌های داخلی برای احراز هویت و مجوزها، امنیت API شما را تضمین می‌کنند.
• انعطاف‌پذیری: به شما اجازه می‌دهد تا هر جنبه‌ای از API خود را سفارشی‌سازی کنید.

شروع کار: نصب و راه‌اندازی

برای شروع کار با Django REST Framework، مراحل زیر را دنبال کنید:

1. 1. ایجاد یک محیط مجازی (Virtual Environment):

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

   
   python -m venv myenv
   source myenv/bin/activate  # در لینوکس/مک
   myenvScriptsactivate     # در ویندوز
               

2. 2. نصب Django و Django REST Framework:

   حالا که محیط مجازی فعال است، می‌توانید جنگو و DRF را نصب کنید:

   
   pip install django djangorestframework
               

3. 3. ایجاد پروژه جنگو:

   یک پروژه جدید جنگو ایجاد کنید:

   
   django-admin startproject myproject .
               

   (نقطه “.” باعث می‌شود پروژه در همان دایرکتوری فعلی ایجاد شود.)

4. 4. ایجاد برنامه (App) در جنگو:

   هر بخش از عملکرد API شما می‌تواند در یک App جداگانه قرار گیرد. مثلاً برای مدیریت کاربران:

   
   python manage.py startapp myapp
               

5. 5. پیکربندی پروژه:

   فایل settings.py را در پوشه myproject باز کنید و 'rest_framework' و اسم برنامه خود (اینجا 'myapp') را به INSTALLED_APPS اضافه کنید:

   
   # myproject/settings.py
   
   INSTALLED_APPS = [
       # ...
       'rest_framework',
       'myapp', # نام برنامه شما
   ]
               

   در همین فایل settings.py می‌توانید یک سری تنظیمات پیش‌فرض برای DRF اضافه کنید. مثلاً برای فعال کردن Browseable API و استفاده از JSON رندرینگ:

   
   # myproject/settings.py
   
   REST_FRAMEWORK = {
       'DEFAULT_RENDERER_CLASSES': [
           'rest_framework.renderers.JSONRenderer',
           'rest_framework.renderers.BrowsableAPIRenderer', # برای رابط کاربری قابل مرور
       ],
       'DEFAULT_PARSER_CLASSES': [
           'rest_framework.parsers.JSONParser',
       ]
       # می‌توانید Default authentication, permission و غیره را هم اینجا تعریف کنید
   }
               

6. 6. اعمال میگریشن‌ها:

   فراموش نکنید که تغییرات دیتابیس (حتی برای اولین بار) را اعمال کنید:

   
   python manage.py makemigrations
   python manage.py migrate
               

مفاهیم کلیدی Django REST Framework

برای اینکه بتوانید با DRF کار کنید، باید با چند مفهوم اصلی آشنا شوید:

Serializers: تبدیل داده‌ها

در هسته هر API، تبدیل داده‌ها قرار دارد. Serializerها در DRF این کار را انجام می‌دهند. آنها مسئول تبدیل مدل‌های پیچیده جنگو (مانند یک آبجکت از دیتابیس) به فرمت‌های ساده‌تر مثل JSON یا XML هستند که قابلیت ارسال از طریق شبکه را دارند. همچنین، آنها می‌توانند داده‌های ورودی را اعتبارسنجی کرده و به آبجکت‌های پایتون تبدیل کنند.

# myapp/serializers.py
from rest_framework import serializers
from .models import MyModel # فرض می‌کنیم یک مدل به نام MyModel دارید

class MyModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = '__all__' # همه فیلدها را سریالایز می‌کند
        # fields = ['id', 'name', 'description'] # می‌توانید فیلدهای خاصی را انتخاب کنید
    

Views: منطق تجاری API

Viewها در DRF دقیقاً مثل Viewهای جنگو عمل می‌کنند، اما به جای برگرداندن HTML، پاسخ‌های HTTP (معمولاً JSON) را برمی‌گردانند. DRF انواع مختلفی از Viewها را ارائه می‌دهد:

• APIView: ساده‌ترین نوع View است که به شما کنترل کاملی بر روی نحوه مدیریت درخواست‌های HTTP (GET, POST, PUT, DELETE) می‌دهد.
• Generic Views: مجموعه‌ای از Viewهای از پیش ساخته شده برای عملیات CRUD (Create, Retrieve, Update, Delete) که کدنویسی را بسیار کاهش می‌دهند. مثلاً ListAPIView برای دریافت لیست، RetrieveAPIView برای دریافت یک آیتم خاص و …
• ViewSets: راهی قدرتمندتر و سازمان‌یافته‌تر برای مدیریت Viewها. آنها به شما اجازه می‌دهند تا منطق مربوط به یک مدل را در یک کلاس واحد تعریف کنید و سپس با استفاده از Routerها، URLها را به صورت خودکار ایجاد کنید.

# myapp/views.py
from rest_framework import generics
from .models import MyModel
from .serializers import MyModelSerializer

class MyModelListCreate(generics.ListCreateAPIView):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer

class MyModelRetrieveUpdateDestroy(generics.RetrieveUpdateDestroyAPIView):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer
    

Routers: مدیریت آسان URLها

وقتی از ViewSetها استفاده می‌کنید، DRF Routerها به شما کمک می‌کنند تا به صورت خودکار URLها را برای عملیات CRUD مختلف ایجاد کنید. این کار باعث می‌شود فایل urls.py شما بسیار تمیزتر و کوتاه‌تر باشد.

# myproject/urls.py (مثال برای ViewSet)
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from myapp.views import MyModelViewSet # فرض می‌کنیم یک ViewSet دارید

router = DefaultRouter()
router.register(r'mymodels', MyModelViewSet)

urlpatterns = [
    path('api/', include(router.urls)),
]
    

Request & Response: قلب ارتباطات

DRF کلاس‌های Request و Response خود را ارائه می‌دهد که قابلیت‌های بیشتری نسبت به همتایان جنگویی خود دارند. برای مثال، Request می‌تواند نوع محتوای ارسالی (JSON، XML و غیره) را به صورت خودکار تشخیص دهد و Response می‌تواند داده‌های شما را به فرمت‌های مختلف رندر کند.

ساخت اولین API با DRF (مثال عملی: لیست وظایف)

بیایید با هم یک API ساده برای مدیریت لیست وظایف (Todo List) بسازیم.

1. 1. تعریف مدل (Model) در todo/models.py:

   یک مدل ساده برای وظایف تعریف می‌کنیم.

   
   # todo/models.py
   from django.db import models
   
   class Todo(models.Model):
       title = models.CharField(max_length=200)
       description = models.TextField(blank=True)
       completed = models.BooleanField(default=False)
       created_at = models.DateTimeField(auto_now_add=True)
   
       def __str__(self):
           return self.title
               

   بعد از تعریف مدل، میگریشن‌ها را اعمال کنید:

   
   python manage.py makemigrations todo
   python manage.py migrate
               

2. 2. ایجاد سریالایزر (Serializer) در todo/serializers.py:

   این فایل را ایجاد کنید و سریالایزر مدل Todo را بنویسید:

   
   # todo/serializers.py
   from rest_framework import serializers
   from .models import Todo
   
   class TodoSerializer(serializers.ModelSerializer):
       class Meta:
           model = Todo
           fields = '__all__' # همه فیلدهای مدل Todo را شامل می‌شود
               

3. 3. تعریف Viewها در todo/views.py:

   از Generic Views برای سرعت بخشیدن به کار استفاده می‌کنیم.

   
   # todo/views.py
   from rest_framework import generics
   from .models import Todo
   from .serializers import TodoSerializer
   
   class TodoListCreate(generics.ListCreateAPIView):
       queryset = Todo.objects.all()
       serializer_class = TodoSerializer
   
   class TodoRetrieveUpdateDestroy(generics.RetrieveUpdateDestroyAPIView):
       queryset = Todo.objects.all()
       serializer_class = TodoSerializer
               

4. 4. تعریف URLها:

   ابتدا یک فایل urls.py در پوشه todo ایجاد کنید و مسیرهای API را تعریف کنید:

   
   # todo/urls.py
   from django.urls import path
   from .views import TodoListCreate, TodoRetrieveUpdateDestroy
   
   urlpatterns = [
       path('todos/', TodoListCreate.as_view(), name='todo-list-create'),
       path('todos//', TodoRetrieveUpdateDestroy.as_view(), name='todo-detail'),
   ]
               

   سپس، این URLها را به فایل اصلی myproject/urls.py اضافه کنید:

   
   # myproject/urls.py
   from django.contrib import admin
   from django.urls import path, include
   
   urlpatterns = [
       path('admin/', admin.site.urls),
       path('api/', include('todo.urls')), # اضافه کردن URLهای API
   ]
               

5. 5. تست API:

   سرور توسعه جنگو را راه‌اندازی کنید:

   
   python manage.py runserver
               

   حالا می‌توانید به http://127.0.0.1:8000/api/todos/ مراجعه کنید. با Browseable API در مرورگر، می‌توانید لیست وظایف را ببینید، وظیفه جدید اضافه کنید، و جزئیات هر وظیفه را ویرایش یا حذف کنید (با رفتن به /api/todos/1/ مثلاً).

مقایسه Django REST Framework با سایر روش‌ها

برای درک بهتر ارزش DRF، خوب است آن را با سایر رویکردها مقایسه کنیم:

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

عیب‌یابی سریع (Troubleshooting)

در طول توسعه با DRF، ممکن است با مشکلاتی مواجه شوید. در اینجا به چند مشکل رایج و راه‌حل آنها اشاره می‌کنیم:

• خطا: Page not found (404) برای API شما.

  راه‌حل:

  1. مطمئن شوید که 'rest_framework' و App خود را به INSTALLED_APPS در settings.py اضافه کرده‌اید.
  2. بررسی کنید که include('your_app.urls') را در project/urls.py اضافه کرده باشید.
  3. مسیرهای (paths) تعریف شده در app/urls.py را با دقت بررسی کنید که دقیقاً با مسیرهایی که درخواست می‌کنید، مطابقت داشته باشند.
• خطا: Serializer validation errors (مثلاً "field is required").

  راه‌حل:

  1. مطمئن شوید که تمام فیلدهای لازم را در درخواست POST یا PUT خود ارسال می‌کنید.
  2. نوع داده فیلدها را بررسی کنید. مثلاً اگر یک فیلد BooleanField است، باید true یا false ارسال کنید نه رشته.
  3. اگر از Browsable API استفاده می‌کنید، ممکن است به صورت پیش‌فرض همه فیلدها را نمایش ندهد؛ فیلدهای ضروری را دستی اضافه کنید.
• خطا: "Authentication credentials were not provided."

  راه‌حل:

  1. این خطا معمولاً نشان می‌دهد که شما از مکانیزم‌های احراز هویت استفاده می‌کنید. اگر در حال توسعه هستید و نیازی به احراز هویت ندارید، می‌توانید آن را به صورت موقت در View یا در تنظیمات کلی DRF غیرفعال کنید (مثلاً با اضافه کردن permission_classes = [AllowAny] به View).
  2. اگر قصد استفاده از احراز هویت را دارید، مطمئن شوید که توکن (Token) یا کوکی (Cookie) لازم را در هدر درخواست خود ارسال می‌کنید.
• خطا: Method Not Allowed (405).

  راه‌حل:

  1. این خطا یعنی متد HTTP که استفاده می‌کنید (مثلاً PUT یا DELETE) برای آن URL پشتیبانی نمی‌شود.
  2. مطمئن شوید که از ViewSet یا Generic View مناسب استفاده می‌کنید که متد مورد نظر شما را پشتیبانی می‌کند. مثلاً ListAPIView فقط GET را پشتیبانی می‌کند، اما ListCreateAPIView هم GET و هم POST را.

سوالات متداول (FAQ)

نتیجه‌گیری

Django REST Framework ابزاری بی‌نظیر برای هر توسعه‌دهنده‌ای است که با جنگو کار می‌کند و نیاز به ساخت API دارد. با یادگیری مفاهیم اصلی آن مثل Serializerها، Viewها و Routerها، می‌توانید به سرعت APIهای قدرتمند، امن و مقیاس‌پذیر بسازید.

این مقاله یک راهنمای مقدماتی بود تا شما را با دنیای DRF آشنا کند. اما این تازه آغاز راه است. DRF قابلیت‌های بسیار پیشرفته‌تری نظیر Pagination، Filtering، Search، Throttling و Custom Fields را نیز ارائه می‌دهد که با کاوش و تمرین بیشتر می‌توانید به آنها مسلط شوید. امیدواریم این آموزش، دید مناسبی برای شروع سفر شما در دنیای توسعه API با Django REST Framework فراهم کرده باشد.

با تمرین و تکرار، مسیر شما برای تبدیل شدن به یک متخصص DRF هموار خواهد شد.