Aller au contenu principal

Comment penser une API avec Django DRF

Repères utiles :

info

Cette note explique comment raisonner correctement avant d'écrire une API avec Django DRF. Le but n'est pas de commencer par des endpoints au hasard, mais de comprendre le problème, les ressources, les acteurs, les règles métier et les responsabilités du backend.

1. Le vrai danger quand on commence une API​

Quand on débute avec Django DRF, on a souvent envie de faire tout de suite ceci :

  • créer un modèle
  • créer un serializer
  • créer un viewset
  • brancher un router
  • tester l'endpoint

Techniquement, on peut. Mais conceptuellement, c'est souvent trop tôt.

Pourquoi ? Parce qu'une API mal pensée peut vite devenir :

  • confuse
  • trop couplée au frontend
  • incohérente
  • difficile à faire évoluer
  • fragile côté permissions

Donc avant le code, il faut un modèle mental clair.

2. Une définition simple de ce qu'est une API​

Une API est une interface qui permet à un client de demander au backend d'accéder à des données ou d'effectuer certaines actions selon des règles précises.

Dans un projet Django DRF, le client peut être :

  • un frontend React ou Next.js
  • une application mobile
  • un autre backend
  • un outil interne
  • un script automatisé

Le backend n'est donc pas là pour “montrer la base de données”. Il est là pour exposer des capacités contrôlées.

3. Première idée fondamentale : partir du problème, pas des endpoints​

La mauvaise approche est :

“quels endpoints vais-je créer ?”

La bonne approche est :

“quel problème réel le backend doit-il résoudre ?”

Exemple : si tu construis un outil de gestion de projets, la vraie question n'est pas d'abord :

  • /projects/
  • /tasks/
  • /users/

La vraie question est :

  • qui utilise le système ?
  • que veulent faire ces personnes ?
  • quelles données doivent être manipulées ?
  • quelles règles protègent ces actions ?
  • quelles informations doivent être visibles ou cachées ?

4. Deuxième idée fondamentale : penser en ressources​

Avec Django DRF, il est très utile de penser en ressources.

Une ressource est une chose importante de ton domaine.

Exemples :

  • un utilisateur
  • un projet
  • une tâche
  • une commande
  • une facture
  • une analyse IA
  • un rapport

Pour chaque ressource, tu peux poser les questions suivantes :

  • qui peut la lire ?
  • qui peut la créer ?
  • qui peut la modifier ?
  • qui peut la supprimer ?
  • quelles informations de cette ressource doivent être exposées ?

5. Troisième idée fondamentale : penser en acteurs​

Une API n'est jamais réellement neutre. Elle sert toujours des acteurs différents.

Exemples d'acteurs :

  • visiteur non connecté
  • utilisateur standard
  • manager
  • administrateur
  • client externe
  • système interne

Ces acteurs n'ont généralement pas les mêmes droits ni les mêmes besoins.

Donc une API bien pensée doit toujours se demander :

  • pour qui cette route existe-t-elle ?
  • pour quel niveau d'accès ?
  • avec quelles limites ?

6. Quatrième idée fondamentale : penser en règles métier​

Une API n'est pas juste un tuyau de données. Elle est aussi le gardien de certaines règles.

Exemples de règles métier :

  • un utilisateur ne peut voir que ses propres documents
  • un manager peut modifier les tâches de son équipe mais pas les utilisateurs d'une autre équipe
  • une commande payée ne peut plus être annulée dans certains cas
  • un rapport ne peut être validé que s'il est complet

Ce sont ces règles qui donnent du sens au backend.

7. Ce qu'une bonne API doit faire​

Une bonne API doit :

  • exposer clairement ce qui est utile
  • protéger ce qui ne doit pas être public
  • refléter les vrais cas d'usage du produit
  • rester cohérente d'un endpoint à l'autre
  • être compréhensible pour l'équipe qui la maintient

Autrement dit, une bonne API n'est pas celle qui a “beaucoup de routes”. C'est celle qui répond correctement aux bons besoins.

8. Ce qu'une mauvaise API fait souvent​

Une mauvaise API fait souvent l'une de ces choses :

  • elle expose brutalement les tables comme si c'était le produit
  • elle copie l'interface frontend sans recul
  • elle mélange plusieurs responsabilités dans le même endpoint
  • elle ignore les permissions jusqu'à la fin
  • elle nomme mal les ressources
  • elle devient incohérente au fur et à mesure

9. La bonne séquence de réflexion​

Avant d'implémenter une API avec Django DRF, tu peux suivre cette séquence.

Étape 1 — Clarifier le besoin produit​

Pose-toi :

  • quel problème le système doit-il résoudre ?
  • qui sont les utilisateurs ?
  • quelles actions sont réellement nécessaires ?

Étape 2 — Identifier les ressources principales​

Liste les objets métier centraux. Ne pense pas seulement technique. Pense domaine.

Étape 3 — Identifier les acteurs et leurs droits​

Demande-toi qui peut :

  • voir
  • créer
  • modifier
  • supprimer
  • valider
  • exporter
  • administrer

Étape 4 — Identifier les règles métier non négociables​

Qu'est-ce qui doit toujours être vrai ? Qu'est-ce qui ne peut pas être contourné ?

Étape 5 — Définir la représentation de la donnée​

Quelles informations veux-tu montrer au client ? Faut-il tout renvoyer ? Souvent non.

Étape 6 — Décider des points d'entrée API​

Seulement après les étapes précédentes, on décide des endpoints.

10. Très important : une API n'est pas une simple copie de la base​

C'est un piège extrêmement fréquent.

On a un modèle en base, donc on crée immédiatement :

  • une route list
  • une route detail
  • create
  • update
  • delete

Parfois c'est pertinent. Parfois non.

Exemple : si ton produit a une notion de “validation de dossier”, l'action importante n'est peut-être pas juste “update dossier”. L'action importante est peut-être :

  • soumettre un dossier
  • valider un dossier
  • rejeter un dossier

Ce sont des intentions métier, pas seulement des opérations CRUD abstraites.

11. Penser à l'échelle du produit, pas seulement à l'échelle de la route​

Une erreur classique consiste à raisonner route par route. Mais une bonne API se pense à l'échelle du produit.

Questions utiles :

  • quelles routes forment un parcours cohérent ?
  • quelles données le frontend devra demander ensemble ?
  • quelles permissions doivent rester homogènes ?
  • quel découpage restera compréhensible dans six mois ?

12. Le rôle de Django DRF dans cette réflexion​

Django DRF ne décide pas pour toi du sens du produit. En revanche, il fournit une structure idéale pour traduire une bonne réflexion en implémentation.

Par exemple :

  • les modèles représentent les objets métier
  • les serializers représentent et valident les données échangées
  • les views / viewsets portent la logique d'accès
  • les permissions protègent les ressources
  • les routers organisent les points d'entrée

Tu retrouveras ces éléments dans Les briques de base de Django DRF.

13. Comment éviter de trop coller au frontend​

Quand un frontend existe, il peut pousser à construire une API trop dépendante de son état actuel.

Le danger est de créer une API qui reflète seulement :

  • un écran précis
  • un composant précis
  • un besoin d'interface temporaire

Une meilleure approche consiste à se demander :

  • quelle ressource ou capacité produit est derrière cet écran ?
  • cette route a-t-elle du sens indépendamment de l'interface actuelle ?
  • si le frontend change, l'API reste-t-elle logique ?

14. Comment penser la sécurité dès le début​

La sécurité ne doit pas être une couche ajoutée à la fin.

Dès la conception, il faut se demander :

  • qui appelle cette route ?
  • avec quel mode d'authentification ?
  • que peut voir cet acteur ?
  • que peut-il modifier ?
  • sur quelles données ?

Si tu attends la fin pour te poser ces questions, tu risques de devoir tout revoir.

15. Une petite méthode pratique de conception​

Quand tu réfléchis à une future API, prends une ressource centrale et remplis mentalement cette grille.

Ressource​

Exemple : Project

Acteurs​

  • admin
  • manager
  • membre
  • visiteur

Actions​

  • lister
  • consulter
  • créer
  • modifier
  • archiver

Règles​

  • un membre ne voit que les projets auxquels il est affecté
  • un manager ne modifie que les projets de son périmètre
  • seuls certains rôles peuvent archiver

Données exposées​

  • certaines visibles pour tous les membres
  • certaines réservées aux managers ou admins

Cette simple grille clarifie énormément les choses.

16. Les cinq questions à se poser avant chaque endpoint​

Avant de créer un endpoint, pose-toi :

  1. Quel besoin réel couvre-t-il ?
  2. Quelle ressource ou action métier représente-t-il ?
  3. Qui a le droit de l'utiliser ?
  4. Quelles données doivent entrer et sortir ?
  5. Restera-t-il cohérent si le produit grandit ?

Si tu ne sais pas répondre clairement, l'endpoint est probablement encore mal pensé.

17. Erreurs fréquentes​

Erreur 1 — Commencer par le CRUD avant de comprendre le domaine​

On code plus vite au début, mais on paie le prix plus tard.

Erreur 2 — Exposer trop de données​

Tout ce qui existe en base n'a pas vocation à être public via l'API.

Erreur 3 — Reporter la question des permissions​

Très mauvais réflexe. Les permissions façonnent l'architecture.

Erreur 4 — Créer des routes trop techniques​

Une API doit parler le langage du produit autant que possible.

Erreur 5 — Faire une API qui épouse uniquement l'UI actuelle​

L'interface change souvent. Le backend doit rester plus stable.

18. Intuition finale​

La meilleure manière de penser une API avec Django DRF est la suivante :

partir du problème, identifier les ressources, comprendre les acteurs, poser les règles métier, puis seulement traduire tout cela en routes, serializers et permissions.

19. Résumé final​

Une API bien pensée avec Django DRF ne se construit pas en enchaînant mécaniquement modèle, serializer, viewset et router.

Elle se construit d'abord en répondant à des questions de fond :

  • quel est le besoin réel ?
  • quelles sont les ressources importantes ?
  • quels sont les acteurs ?
  • quelles sont les règles métier ?
  • que faut-il exposer et protéger ?

Django DRF devient alors très puissant parce qu'il offre une structure claire pour implémenter ces décisions proprement.

20. Pour aller plus loin​

Lire ensuite :