🐍 Django REST Framework – Guide Approfondi

Les 4 Piliers de DRF

Quand utiliser DRF ?

Utilisez DRF si :

• Votre backend doit servir de données à un **frontend séparé** (React, Vue, Angular).
• Vous construisez une **application mobile** qui a besoin d'un backend.
• Vous exposez une **API publique** ou privée pour des partenaires.
• Vous voulez standardiser la communication entre microservices.

Quand est-ce *overkill* ?

N'utilisez pas DRF (ou une API) si :

• Votre projet est un **site web 100% traditionnel** (ex: blog, site vitrine) où Django rend tous les templates HTML.
• Vous avez juste besoin de 1 ou 2 "endpoints" simples. Une vue Django classique retournant un JsonResponse peut suffire.

Alternatives Populaires

1. Django-Ninja

• Approche : "API-first", très moderne, s'inspire de FastAPI.
• Avantage : Utilise la **validation de type Pydantic** (très puissant) et génère automatiquement une documentation OpenAPI (Swagger/Redoc) de haute qualité.
• Inconvénient : Moins mature que DRF, écosystème plus petit.

2. FastAPI (Framework Python, pas Django)

• Approche : Un micro-framework Python dédié aux APIs, basé sur Starlette et Pydantic.
• Avantage : Extrêmement rapide (performance asynchrone), validation de type intégrée, documentation auto.
• Inconvénient : N'inclut pas l'écosystème Django (pas d'Admin, pas d'ORM Django, pas de système d'authentification complet par défaut).

DRF vs. Ninja : Lequel choisir ?

En 2025, le choix se résume souvent à :

• Prenez DRF : Si vous avez un **projet Django existant** à transformer en API, ou si vous tenez à l'écosystème d'addons de DRF (ex: `drf-spectacular`, `djoser`). C'est le choix le plus robuste et testé.
• Prenez Django-Ninja : Si vous démarrez un **nouveau projet Django** et que votre priorité absolue est la **performance** et la **documentation OpenAPI** automatique.

Configuration Globale de DRF

Toutes les configurations globales de DRF se font dans un dictionnaire REST_FRAMEWORK dans votre settings.py.

Voici une configuration de **départ solide** et sécurisée pour la plupart des projets :

# settings.py

REST_FRAMEWORK = {
    
    # --- AUTHENTIFICATION ---
    # Par défaut : Token (pour scripts/apps) et Session (pour l'API browsable)
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.TokenAuthentication',
        'rest_framework.authentication.SessionAuthentication', 
    ],

    # --- PERMISSIONS ---
    # Politique par défaut : Tout est fermé, sauf si authentifié.
    # (Alternative : IsAuthenticatedOrReadOnly pour autoriser lecture)
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],

    # --- PAGINATION ---
    # Active la pagination globale pour toutes les listes
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 25, # Nombre d'items par page

    # --- FILTRAGE ---
    'DEFAULT_FILTER_BACKENDS': [
        'django_filters.rest_framework.DjangoFilterBackend',
        'rest_framework.filters.SearchFilter',
        'rest_framework.filters.OrderingFilter',
    ],
    
    # --- SCHÉMA & DOCS ---
    # Utilise drf-spectacular (à installer) pour générer OpenAPI 3.0
    # 'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

Sécurité : Ne jamais coder en dur !

Votre configuration REST_FRAMEWORK ne doit pas contenir de clés secrètes. Cependant, d'autres paramètres (comme ceux pour Sentry ou les BDD) le feront.

Utilisez toujours des variables d'environnement (via python-dotenv).

Exemple avec .env

# .env (à la racine du projet, dans .gitignore)
DJANGO_SECRET_KEY="votre-secret-key-ici"
DJANGO_DEBUG=True
SENTRY_DSN="https://..."

Utilisation dans settings.py

# settings.py
from dotenv import load_dotenv
import os
load_dotenv() # Charge le fichier .env

SECRET_KEY = os.getenv("DJANGO_SECRET_KEY")
DEBUG = os.getenv("DJANGO_DEBUG", "False") == "True"

# Exemple de configuration de Sentry (addon populaire)
import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

SENTRY_DSN = os.getenv("SENTRY_DSN")
if SENTRY_DSN:
    sentry_sdk.init(
        dsn=SENTRY_DSN,
        integrations=[DjangoIntegration()],
        traces_sample_rate=0.2,
    )

Ajout des URLs de base

Pour utiliser l'API "Browsable" et l'authentification par Token, vous devez ajouter quelques URLs au fichier urls.py principal de votre projet.

# ideolab_site/urls.py
from django.contrib import admin
from django.urls import path, include
from rest_framework.authtoken import views as authtoken_views

urlpatterns = [
    path('admin/', admin.site.urls),
    
    # --- URLs de base DRF ---
    
    # 1. URLs de l'API (ex: /api/v1/)
    # On délègue toutes nos URLs d'API à un fichier séparé
    path('api/v1/', include('core.api_urls')), # 'core' est un exemple d'app

    # 2. API "Browsable" (Login / Logout)
    # Requis pour pouvoir se connecter/déconnecter de l'interface web
    path('api-auth/', include('rest_framework.urls')),
    
    # 3. Authentification par Token
    # Permet à un client de faire un POST avec 'username' et 'password'
    # pour obtenir un Token en retour.
    path('api-token-auth/', authtoken_views.obtain_auth_token),

    # ... vos autres urls ...
]

Validation

[...Contenu détaillé sur la validation de champ (validate_field) et la validation d'objet (validate)...]

[...Exemple de code pour valider un titre...]
def validate_title(self, value):
    if "Django" not in value:
        raise serializers.ValidationError("Le titre doit contenir 'Django'")
    return value

Relations (Foreign Key, ManyToMany)

[...Contenu détaillé sur PrimaryKeyRelatedField, StringRelatedField, Nested Serializers et SlugRelatedField...]

Champs Avancés

[...Contenu détaillé sur SerializerMethodField, ReadOnlyField, et comment gérer l'écriture (write-only)...]

Pièges & Bonnes Pratiques

[...Contenu détaillé sur le problème N+1 (select_related, prefetch_related) et la gestion des champs "write-only" (ex: mot de passe)...]

Vues Génériques (ListCreateAPIView, RetrieveUpdateDestroyAPIView)

[...Contenu détaillé sur les vues génériques, un bon compromis entre APIView et ViewSets...]

ModelViewSet

[...Contenu détaillé sur ModelViewSet, le moyen le plus rapide de créer un CRUD complet. Définition de queryset et serializer_class...]

[...Exemple de code ArticleViewSet...]
class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    permission_classes = [IsAuthenticated, IsAuthorOrReadOnly]

Actions Personnalisées (@action)

[...Contenu détaillé sur l'ajout d'endpoints personnalisés à un ViewSet (ex: /api/articles/1/publish/)...]

[...Exemple de code pour @action(detail=True)...]

Permissions Incluses

[...Contenu détaillé sur IsAuthenticated, IsAdminUser, IsAuthenticatedOrReadOnly, AllowAny...]

Permissions Personnalisées

[...Contenu détaillé sur la création d'une permission personnalisée en héritant de BasePermission et en surchargeant has_object_permission()...]

[...Exemple de permission IsAuthorOrReadOnly...]

JWT & OAuth2

[...Contenu détaillé sur les alternatives au Token simple. Présentation de Simple-JWT et Django-OAuth-Toolkit...]

Configuration

[...Contenu détaillé sur la création d'un fichier `api_urls.py` dans une app, et comment l'inclure dans le `urls.py` principal...]

[...Exemple de code pour un router.register()...]
from rest_framework.routers import DefaultRouter
from . import views

router = DefaultRouter()
router.register(r'articles', views.ArticleViewSet, basename='article')
router.register(r'users', views.UserViewSet, basename='user')

urlpatterns = router.urls

Routage Imbriqué

[...Contenu détaillé sur la création d'URLs imbriquées (ex: /api/articles/1/comments/2/) avec `drf-nested-routers`...]

Filtrage (django-filter)

[...Contenu détaillé sur l'utilisation de `django-filter` pour permettre des filtres sur les query params (ex: /api/articles/?author=1&published=true)...]

Recherche & Ordre

[...Contenu détaillé sur `SearchFilter` (/?search=...) et `OrderingFilter` (/?ordering=-created_at)...]

serializers.py

[...ArticleSerializer (avec `author` en `ReadOnlyField`) et CommentSerializer...]

views.py

[...ArticleViewSet (avec permission `IsAuthorOrReadOnly`) et CommentViewSet (avec permission `IsOwnerOrReadOnly`). Surcharge de `perform_create` pour lier l'auteur...]

api_urls.py

[...Utilisation de `drf-nested-routers` pour avoir /api/articles/<id>/comments/...]