Créez un premier endpoint
En avant, mettons en place ce premier endpoint en permettant à nos visiteurs d’accéder à la liste des catégories de nos produits.
La toute première chose à faire lors de la réalisation d’un endpoint est de se demander quelles sont les informations importantes que nous souhaitons en tirer.
Dans notre cas, pour afficher la liste des catégories, nous allons avoir besoin de leur nom, mais également de leur identifiant. L’identifiant sera utile aux clients (application front, mobile…) pour identifier de manière claire et unique les catégories s’ils ont des actions à faire dessus, comme afficher les produits qui constituent une catégorie.
DRF met à notre disposition des serializers qui permettent de transformer nos models Django en un autre format qui, lui, est exploitable par une API.
Lorsque notre API sera consultée, le serializer va nous permettre de transformer notre objet en un JSON et, inversement, lorsque notre API va recevoir du JSON, elle sera capable de le transformer en un objet.
Pour le développeur qui les utilise, ils fonctionnent à la manière des formulaires proposés par Django. C'est-à-dire qu’ils sont paramétrés en précisant le model à utiliser et les champs de ce model à sérialiser.
Créons un fichier serializers.py et écrivons notre premier serializer, que nous nommerons CategorySerializer pour rester clair et précis. ;)
Il est nécessaire de définir sa classe Meta et la liste des champs, exactement comme pour un formulaire. De plus, les noms des attributs sont identiques.
from rest_framework.serializers import ModelSerializer
from shop.models import Category
class CategorySerializer(ModelSerializer):
class Meta:
model = Category
fields = ['id', 'name']Occupons-nous à présent de la View. DRF nous propose une APIView qui a également un fonctionnement similaire aux Views de Django.
Nous devons réécrire la méthode get qui réalisera les actions suivantes :
Récupérer toutes les catégories en utilisant l’ORM de Django ;
Sérialiser les données à l’aide de notre serializer ;
Renvoyer une réponse qui contient les données sérialisées.
from rest_framework.views import APIView
from rest_framework.response import Response
from shop.models import Category
from shop.serializers import CategorySerializer
class CategoryAPIView(APIView):
def get(self, *args, **kwargs):
categories = Category.objects.all()
serializer = CategorySerializer(categories, many=True)
return Response(serializer.data)Le paramètre many permet de préciser au Serializer qu’il va devoir générer une liste d’éléments à partir de l’itérable (notre queryset) qui lui est transmis.
Et si je n’ai qu’un seul élément à sérialiser ?
Dans ce cas, il n’est pas nécessaire de préciser le paramètre many, et l’objet peut directement être donné au Serializer sans le mettre dans un itérable.
Enfin, pour obtenir les données sérialisées, nous appelons la propriété data de notre serializer. Ce sont ces données qui sont utilisées pour construire la réponse.
Il ne reste plus qu’à créer l’URL correspondante et l’associer à notre View :
from django.contrib import admin
from django.urls import path, include
from shop.views import CategoryAPIView
urlpatterns = [
path('admin/', admin.site.urls),
path('api-auth/', include('rest_framework.urls')),
path('api/category/', CategoryAPIView.as_view())
]Notre endpoint est maintenant accessible sur l’URLhttp://127.0.0.1:8000/api/category/ .
L’interface proposée par DRF nous permet de voir également le status code obtenu. Dans notre cas, 200, qui indique un succès.
Revenons sur la mise en place d'un endpoint dans le screencast ci-dessous :
N’hésitez pas à jouer avec notre nouveau serializer, lui ajouter des champs, comme les dates de création et de modification. Tentez l’écriture pour les autres méthodes HTTP, l’expérimentation est un levier !
Découvrez les méthodes d’un endpoint
Seul GET est accessible sur notre endpoint, car nous n’avons redéfini que la méthode get dans la View. Ne pas réécrire de méthodes permet de ne pas les rendre accessibles. Nous pourrions réécrire également les méthodes post, patch et delete.
GET et POST servent avec Django à créer de nouvelles entités au travers de formulaires, mais PATCH et DELETE servent à quoi ?
Reprenons-les une par une pour voir réellement à quoi servent ces méthodes HTTP dans le cadre d’une API, et les différences avec un site Internet classique :
GET : Permet la lecture d'informations.
Un peu comme un site Internet classique, les appels en GET renvoient des données qui sont généralement du HTML qui est lu et rendu dans le navigateur. Dans le cas d’une API, il s’agit de JSON.POST : Permet la création d’entités.
Alors que sur un site les appels en POST peuvent être utilisés pour modifier une entité, dans le cas d’une API, les POST permettent la création.PATCH : Permet la modification d’une entité.
PATCH permet la modification de tout ou partie des valeurs des attributs d’une entité pour une API, alors que pour un site classique, nous utilisons un formulaire et un POST.DELETE : Permet la suppression d’une entité.
DELETE permet la suppression d’une entité pour une API, alors que pour un site classique, nous utilisons un formulaire et généralement un POST.PUT : Permet également la modification d’une entité.
Il est peu utilisé en dehors de l’interface de DRF, que nous verrons ensuite. Pour un site classique, l’action de modification entière d’une entité passe également par un POST au travers d’un formulaire.
Pas de panique, tout n’est pas à retenir tout de suite. Durant ce cours, nous allons aborder chacune de ces méthodes dans divers cas pratiques.
Ce qui est important à retenir est que chaque méthode correspond à une action du CRUD (Create, Read, Update, Delete), et c’est cela qui va nous permettre d’agir directement sur nos models.
À vous de jouer
Je vous propose de prendre la main et de mettre en place un nouvel endpoint qui va permettre de lister tous les produits de notre boutique en ligne.
Utilisons l’URL suivante : http://127.0.0.1:8000/api/product/.
Cet endpoint doit retourner les informations suivantes des produits :
Son identifiant
id.Sa date de création
date_created.Sa date de modification
date_updated.Son nom
name.L’identifiant de la catégorie à laquelle il appartient
category.
Pour réaliser cela, vous pouvez partir de la branche P1C3_exercice. Elle contient déjà ce que nous venons de faire ensemble.
Une solution est proposée sur la branche P1C3_solution.
En résumé
Le fonctionnement des serializers proposé par DRF est similaire à celui des formulaires de Django.
Les serializers permettent de faire une représentation de nos models en JSON.
Les méthodes HTTP utilisables sont la représentation du CRUD (Create, Read, Update, Delete).
DRF nous propose une interface web qui permet de visualiser notre API.
N’hésitez pas à modifier les données que retournent le serializer. Imaginez le but de l’endpoint que vous êtes en train de mettre en place pour déterminer quelles sont les données les plus pertinentes à retourner.
