Le framework Django REST Framework (DRF) permet de construire rapidement des interfaces de programmation (API), simplifiant ainsi le processus de développement backend. Une API représente un point d'accès permettant aux applications frontend de récupérer des données, généralement exposé via une URL.

Lors de la mise en place d'une architecture de projet, il est essentiel d'envisager plusieurs aspects pour assurer la robustesse et la maintenabilité, notamment :

• La gestion centralisée des exceptions
• Le contrôle d'accès aux API (autorisation)
• La validation unifiée des paramètres
• L'implémentation simplifiée et homogène de la mise en cache
• L'authentification des utilisateurs
• Le filtrage des requêtes de manière cohérente
• La séparation logique des couches de code

En architecture REST, toute donnée, qu'elle soit récupérée ou manipulée (création, lecture, mise à jour, suppression), est considérée comme une ressource. Cette approche orientée ressource constitue le fondement distinctif de REST par rapport à d'autres styles architecturaux. Certains experts proposent une extension conceptuelle appelée Architecture Orientée Ressource (ROA).

Normes pour la Conception d'API

Une API n'est pas toujours indispensable ; pour des projets individuels ou à petite échelle, l'utilisation directe des moteurs de template de frameworks comme Django peut suffire. Cependant, dans un contexte de développement collaboratif avec séparation frontend-backend, les API deviennent cruciales. Le frontend, par exemple via des requêtes AJAX, interagit avec le backend qui fournit des données au format JSON, plutôt que de recourir au rendu direct de templates.

Le protocole sous-jacent de communication entre l'API et les clients est HTTPS. Voici les conventions clés :

1. Nom de domaine : Deux approches courantes existent :

   • Dédié : https://api.example.com (recommandé, mais potentiellement sujet aux problèmes de cross-domain)
   • Intégré au chemin : https://example.org/api/ (plus simple)

2. Versionnage : Pour gérer les évolutions, le versionnage est appliqué via :

   • Chemin : https://api.example.com/v1/
   • Sous-domaine : https://v1.example.com (peut entraîner des complications liées au cross-domain)

3. Chemins d'accès : Les ressources sont identifiées par des noms (souvent au pluriel) :

   • https://api.example.com/v1/zoos
   • https://api.example.com/v1/animaux

4. Méthodes HTTP : Elles définissent l'opération effectuée :

   • GET : Lecture d'une ou plusieurs ressources
   • POST : Création d'une nouvelle ressource
   • PUT : Mise à jour complète d'une ressource
   • PATCH : Mise à jour partielle d'une ressource
   • DELETE : Suppression d'une ressource

5. Filtrage des données : Les paramètres de requête permettent d'affiner les résultats :

   • https://api.example.com/v1/zoos?limite=10 : Nombre d'enregistrements à retourner
   • https://api.example.com/v1/zoos?decalage=10 : Position de départ dans la liste
   • https://api.example.com/v1/zoos?page=2&par_page=100 : Pagination
   • https://api.example.com/v1/zoos?trier_par=nom&ordre=asc : Tri des résultats
   • https://api.example.com/v1/zoos?type_animal_id=1 : Filtre par attribut spécifique

6. Codes de réponse HTTP : Ils informent du statut de la requête :

   • 200 OK - Données retournées avec succès (opération idempotente)
   • 201 Created - Ressource créée avec succès (POST/PUT/PATCH)
   • 202 Accepted - Requête acceptée pour traitement asynchrone
   • 204 No Content - Suppression réussie sans contenu à retourner
   • 400 Bad Request - Erreur dans la requête client
   • 401 Unauthorized - Authentification requise ou échouée
   • 403 Forbidden - Accès refusé malgré l'authentification
   • 404 Not Found - Ressource introuvable
   • 406 Not Acceptable - Format de réponse non supporté
   • 410 Gone - Ressource définitivement supprimée
   • 422 Unprocessable Entity - Erreur de validation lors de la création/mise à jour
   • 500 Internal Server Error - Erreur interne du serveur

   En cas d'erreur (code 4xx), le message d'erreur doit être retourné, par exemple :

   {"erreur": "Clé d'API non valide"}
   

7. Structure des réponses : Elle varie selon l'opération :

   • GET /collection : Liste de ressources
   • GET /collection/ressource : Détails d'une ressource unique
   • POST /collection : Ressource nouvellement créée
   • PUT /collection/ressource ou PATCH : Ressource mise à jour
   • DELETE /collection/ressource : Document vide ou statut de suppression

8. API Hypermedia : Une API RESTful idéale inclut des liens dans les réponses pour guider l'utilisation des endpoints, comme dans cet exemple : ``` {"hyperlien": { "relation": "collection https://www.example.com/zoos", "url": "https://api.example.com/zoos", "titre": "Liste des zoos", "type_media": "application/vnd.monformat+json" }}