Une API DRF qui démarre avec permission_classes = [IsAuthenticated] et un ModelSerializer généré en cinq minutes fonctionne très bien pour un MVP. Le problème arrive six mois plus tard, quand l'équipe a ajouté des rôles, des objets partagés entre utilisateurs, et des sérialiseurs imbriqués qui ramènent la moitié de la base de données à chaque requête. Ce qui semblait être un détail d'implémentation devient un problème d'architecture.

Le piège des permissions au niveau vue

DRF distingue deux familles de permissions qui sont souvent confondues : les permissions globales (has_permission), évaluées avant d'accéder à la vue, et les permissions d'objet (has_object_permission), évaluées seulement sur les actions qui récupèrent une instance précise (retrieve, update, destroy).

Le piège classique : écrire une permission qui vérifie correctement l'appartenance sur retrieve, mais oublier qu'un list ne passe jamais par has_object_permission. Le queryset du list doit donc filtrer lui-même les objets visibles, sinon la permission d'objet ne protège qu'une partie des endpoints.

from rest_framework.permissions import BasePermission

class IsOwnerOrReadOnly(BasePermission):
    def has_object_permission(self, request, view, obj):
        if request.method in ("GET", "HEAD", "OPTIONS"):
            return True
        return obj.owner_id == request.user.id

Cette permission protège retrieve, update, destroy. Elle ne protège pas list : si le get_queryset() de la vue renvoie Document.objects.all(), n'importe quel utilisateur authentifié voit la liste complète des documents de tous les autres utilisateurs, même s'il ne peut pas les modifier. C'est une fuite de données silencieuse, pas une erreur 403 visible en test manuel.

class DocumentViewSet(ModelViewSet):
    permission_classes = [IsAuthenticated, IsOwnerOrReadOnly]

    def get_queryset(self):
        user = self.request.user
        if user.is_staff:
            return Document.objects.all()
        return Document.objects.filter(owner=user)

La règle à retenir : une permission d'objet protège les actions sur une instance unique, jamais une collection. Le filtrage de collection est la responsabilité du queryset, pas de la classe de permission.

Composer les permissions plutôt que les empiler

Quand les règles se complexifient (propriétaire OU membre d'une équipe OU administrateur), il est tentant d'écrire une seule permission avec une cascade de if. Le code devient vite illisible. DRF permet de composer les permissions avec les opérateurs &, | et ~ :

permission_classes = [IsAuthenticated & (IsOwner | IsTeamMember | IsAdminRole)]

Chaque classe reste testable isolément, et la logique de combinaison est explicite dans la déclaration de la vue plutôt que cachée dans une méthode.

Le piège des sérialiseurs imbriqués et du N+1

Un ModelSerializer avec des champs imbriqués (serializers.SerializerMethodField, ou un sérialiseur enfant référencé via une ForeignKey) déclenche une requête SQL par objet sérialisé si le queryset de la vue ne précharge pas les relations. C'est l'équivalent exact du problème N+1 qu'on connaît en ORM, mais version API : invisible en local avec dix lignes de fixtures, dévastateur en production avec dix mille enregistrements.

class CommentSerializer(serializers.ModelSerializer):
    author = serializers.SerializerMethodField()

    class Meta:
        model = Comment
        fields = ["id", "body", "author"]

    def get_author(self, obj):
        return {"id": obj.author.id, "name": obj.author.get_full_name()}

Sur une liste de cent commentaires, DRF itère et appelle get_author cent fois, chaque appel accédant à obj.author qui, sans préchargement, déclenche une requête. Le correctif se fait au niveau du queryset, pas du sérialiseur :

class CommentViewSet(ModelViewSet):
    serializer_class = CommentSerializer
    queryset = Comment.objects.select_related("author").all()

select_related génère un JOIN SQL pour les relations ForeignKey et OneToOne. Pour les relations ManyToMany ou les reverse ForeignKey (par exemple, précharger tous les tags d'un article), il faut prefetch_related, qui exécute une requête séparée mais unique pour l'ensemble du queryset, plutôt qu'une requête par objet.

queryset = Article.objects.prefetch_related("tags", "comments__author")

Le __ dans comments__author précharge la relation en deux niveaux : les commentaires de l'article, puis l'auteur de chaque commentaire, en deux requêtes au total au lieu de 1 + N + N.

Diagnostiquer avant de corriger

Avant d'ajouter des select_related à l'aveugle, il faut mesurer. django-silk ou le middleware de debug de django-debug-toolbar affichent le nombre de requêtes par endpoint. En ligne de commande, activer le logger SQL de Django donne le même signal sans dépendance supplémentaire :

LOGGING = {
    "version": 1,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "django.db.backends": {
            "handlers": ["console"],
            "level": "DEBUG",
        },
    },
}

Un endpoint qui passe de 1 requête à 101 requêtes quand on passe de une à cent lignes de résultat est le signal typique d'un N+1. L'objectif n'est pas zéro requête supplémentaire, mais un nombre de requêtes constant indépendamment de la taille du résultat.

Sérialiseurs en lecture et en écriture : ne pas réutiliser le même

Un piège fréquent est d'utiliser le même ModelSerializer pour la lecture (GET) et l'écriture (POST/PATCH). Dès que l'API a des champs calculés, des champs sensibles qui ne doivent jamais être modifiables par le client (is_verified, role), ou des représentations imbriquées en lecture mais des identifiants en écriture, un seul sérialiseur devient un compromis bancal truffé de read_only_fields.

class UserPublicSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username", "avatar_url"]


class UserWriteSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["username", "email", "password"]
        extra_kwargs = {"password": {"write_only": True}}

    def create(self, validated_data):
        return User.objects.create_user(**validated_data)

Séparer les deux sérialiseurs rend chaque classe petite et explicite, et surtout empêche qu'un champ sensible (role, is_staff) se retrouve accidentellement acceptable en écriture parce qu'il était présent dans un sérialiseur partagé pour les besoins de la lecture. C'est aussi une question de sécurité : un champ absent d'un sérialiseur d'écriture ne peut tout simplement pas être injecté par un payload malveillant, alors qu'un read_only_fields oublié sur un ajout de champ ultérieur rouvre la faille.

Permissions dynamiques selon l'action

Une autre erreur fréquente est de déclarer une seule liste permission_classes statique sur tout le ViewSet, alors que les règles d'accès diffèrent souvent selon l'action : la création d'un document peut être ouverte à tout utilisateur authentifié, alors que sa suppression doit être réservée au propriétaire ou à un administrateur. Forcer une seule permission commune pousse à écrire une classe qui teste elle-même view.action, ce qui recrée dans la permission la logique de routage que DRF sait déjà faire.

class DocumentViewSet(ModelViewSet):
    def get_permissions(self):
        if self.action in ("create",):
            return [IsAuthenticated()]
        if self.action in ("update", "partial_update", "destroy"):
            return [IsAuthenticated(), IsOwnerOrAdmin()]
        return [IsAuthenticated(), IsOwnerOrReadOnly()]

get_permissions() est appelée à chaque requête et doit retourner des instances, pas des classes, ce qui explique le () après chaque nom. Cette approche garde chaque classe de permission simple et testable isolément, et centralise la logique de routage par action au même endroit que le reste du comportement du ViewSet, plutôt que de la disperser dans des conditions internes à chaque permission.

Validation croisée : validate() contre validate_<champ>

Un sérialiseur DRF offre deux niveaux de validation qu'il est facile de mal utiliser. validate_<nom_du_champ> valide un champ isolément, sans accès aux autres champs du payload. validate() reçoit le dictionnaire complet des données déjà validées champ par champ, et c'est le seul endroit correct pour une règle qui dépend de plusieurs champs à la fois.

class BookingSerializer(serializers.ModelSerializer):
    class Meta:
        model = Booking
        fields = ["id", "start_date", "end_date", "room"]

    def validate_start_date(self, value):
        if value < timezone.now().date():
            raise serializers.ValidationError("La date de début ne peut pas être dans le passé.")
        return value

    def validate(self, attrs):
        if attrs["end_date"] <= attrs["start_date"]:
            raise serializers.ValidationError(
                {"end_date": "La date de fin doit être postérieure à la date de début."}
            )
        return attrs

L'erreur courante est d'essayer de comparer start_date et end_date dans validate_end_date : à ce stade, rien ne garantit que start_date a déjà été validé et présent dans le contexte de la méthode, puisque DRF ne garantit pas l'ordre d'exécution des validations champ par champ entre elles. Une règle inter-champs doit systématiquement vivre dans validate(), jamais dans un validate_<champ> qui tente d'accéder à self.initial_data pour contourner la limite, ce qui réintroduit des données non validées dans une méthode censée ne travailler que sur des données propres.

Quand la solution facile ne suffit plus

select_related et prefetch_related résolvent le N+1 au niveau d'un endpoint donné, mais une API avec des sérialiseurs profondément imbriqués sur plusieurs niveaux (un article avec ses commentaires, chaque commentaire avec ses réactions, chaque réaction avec son auteur) finit par nécessiter soit une pagination stricte combinée à des préchargements ciblés par niveau, soit un changement d'architecture vers des endpoints dédiés qui exposent des vues plus plates. À ce stade, continuer à empiler des prefetch_related imbriqués devient un signal qu'il faut repenser la forme de la ressource exposée, pas seulement optimiser la requête.

Pour les permissions, quand les règles dépendent de plusieurs organisations, de rôles hiérarchiques ou de délégations temporaires, une bibliothèque dédiée comme django-guardian pour les permissions par objet, ou une couche d'autorisation externalisée, devient plus pertinente qu'une pile de classes BasePermission maison.

À retenir

Les permissions d'objet DRF ne protègent jamais une collection : le filtrage de liste se fait dans le queryset. Le N+1 se diagnostique en comptant les requêtes SQL par rapport à la taille du résultat, et se corrige avec select_related/prefetch_related au niveau du queryset de la vue, jamais dans le sérialiseur lui-même. Séparer les sérialiseurs de lecture et d'écriture évite qu'un champ sensible devienne accidentellement modifiable par le client.