Suivez moi sur twitter : https://twitter.com/EricLeCodeur

Qu'est-ce qu'une API ?

API est l'acronyme d'Application Programming Interface (interface de programmation d'application), une solution logicielle qui permet à deux applications de communiquer entre elles.

Dans le cas du développement web, l'application qui s'exécute dans le navigateur appelé 'frontend' communique/envoi une requête au serveur appelé 'backend'

Exemple

Supposons que l'application frontend désir la liste de tous les articles d'un blog, elle pourrait envoyer au serveur une requêtes HTTP

GET https://www.myblog.com/posts

Le serveur Django va traiter cette requête, lire la base de donnée et va retourner la liste des articles en format JSON (texte structuré). Cette liste pourrait ensuite être traité et affiché dans l'application frontend.

Comment Django peut-il savoir comment traiter cette requête ? En faite, il ne le peut pas. Il ne sera pas quoi faire de la requête. C'est pourquoi nous devons créer une API. C’est-à-dire une application serveur qui déterminera comment répondre à différentes requêtes à propos d'une ressource spécifique. Dans ce cas-ci les articles du blog.

À noter que toutes les requêtes au serveurs se font via des actions HTTP.

Requêtes HTTP

Indiquent l'action que l'on souhaite réaliser sur la ressource indiquée. Bien qu'on rencontre également des noms (en anglais), ces méthodes sont souvent appelées verbes HTTP

Voici les actions/verbes HTTP les plus souvent utilisées

GET :
La méthode GET demande une représentation de la ressource spécifiée. Les requêtes GET doivent uniquement être utilisées afin de récupérer des données.

POST :
La méthode POST est utilisée pour envoyer une entité vers la ressource indiquée. Cela entraîne généralement un changement d'état ou des effets de bord sur le serveur.

PUT :
La méthode PUT remplace toutes les représentations actuelles de la ressource visée par le contenu de la requête.

PATCH :
La méthode PATCH est utilisée pour appliquer des modifications partielles à une ressource.

DELETE :
La méthode DELETE supprime la ressource indiquée.

Fin de la théorie

La théorie c’est bien beau mais il est beaucoup plus facile de comprendre un concept en le mettant en pratique.

Nous allons donc dans les sections qui suivent créer un API REST avec Django

Pré-requis : Installation de Python et Django.

La dernière version de Python peut être téléchargé ici : https://www.python.org/downloads/

Suivre les instructions sur ce site selon votre système d'exploitation (MAC, Windows ou Linux)

Pour vérifier si Python est correctement installé vous pouvez exécuter cette commande à partir de votre terminal

python3 --version
# Python 3.9.6

Environnement virtuel

Lorsque l'on travaille sur un projet Python, on est amené à travailler avec plusieurs librairies comme Django et Django REST Framework.

Selon la date de création du projet. Il est possible par exemple que la librairie Django REST Framework ne soit pas exactement au même no de version dans les autres projets.

Comment faire pour permettre à chaque projet d'avoir sa propre version de Python et ses propres versions de librairies ?

Nous allons utiliser les environnements virtuels.

Python met à votre disposition un système qui permet de créer des environnements virtuels.

Une fois l'environnement créé et activé, toutes les librairies installées pourront être utilisé seulement dans l'environnement auquel ils appartiennent.

Comment créer un environnement virtuel

Normalement nous plaçons un environnement virtuel dans le dossier du projet.

Créer et accéder à un dossier pour notre projet

mkdir myblog
cd myblog

À partir de ce dossier vous pouvez maintenant créer l'environnement virtuel qui sera attaché au projet

python3 -m venv env

Ici on lance python3 avec l'option module venv (-m venv). env est le nom que l'on donne à notre environnement virtuel.

Une fois créer vous pouvez l'activer

source env/bin/activate

Voilà c'est tout ! Vous avez maintenant un environnement virtuel Python créer pour votre projet. Normalement le terminal vous indiquera que votre environnement est activé en affichant son nom.

À noter que pour désactiver l'environnement virtuel vous devez exécuter

desactivate

Installation de Django

À partir du dossier projet myblog et avec l'environnement virtuel activé exécuter la commande d'installation suivante :

pip install django

et

pip install djangorestframework

En faite à partir de ce point, chaque fois que je vous demanderai d'exécuter une commande dans le terminal, je vais présumer que vous êtes dans le dossier du projet 'myblog' et que l'environnement virtuel est activé

Création du projet

Django permet de créer une configuration de projet et ensuite plusieurs applications associées à ce projet.

Par exemple le projet 'myblog' pourrait avoir une application pour la gestion des articles et une autre application pour la gestion des commentaires.

Chaque application partage la même configuration de projet.

Il existe une commande Django permettant de créer une configuration de projet.

Exécuter la commande suivante :

django-admin startproject config .

La commande 'startproject' permet de créer une configuration de projet portant le nom 'config'. Le point '.' spécifie que nous voulons que le projet soit créer dans le dossier en cours

Il peut vous sembler étrange que le nom 'config' fut choisie pour le projet. En faite, c'est logique, car il s'agit de la configuration du projet.

Création de l'application

Le projet 'config' est seulement la partie configuration. Pour ajouter des fonctions à votre application, vous devez créer une ou des applications.

Pour ce faire exécuter cette commande :

djangoadmin startapp posts

La commande 'startapp' permet de créer une application portant le nom 'posts' (articles). C'est dans cette application que nous allons créer notre API.

Le projet 'config' et l'application 'posts' ont été créer avec une structure de dossier et des fichiers.

Voici un exemple des fichiers créé :

Tous ces dossiers et fichiers peuvent sembler exhaustif, mais ne vous en faite pas, ils sont là pour simplifier le développement de l'application. Je vais les expliquer un à un en temps et lieu.

Dernier petit point, nous devons ajouter les lignes de code suivantes au fichier de configuration du projet 'config' settings.py

# config/settings/py

INSTALLED_APPS = [
    ...
    ...

    'rest_framework',
    'rest_framework.authtoken',
    'posts',
]

Ici nous indiquons au projet que nous désirons utiliser ces trois applications.

• rest_framework: nous permettra de créer notre API
• rest_framework.authtoken: nous permettra d'ajouter une sécurité à notre API
• posts indique à Django d'utiliser notre application posts

Création notre premier l'API

La première étape est de créer le modèle de donnée Django qui contiendra nos articles

Ouvrez le fichier 'models.py' dans le dossier de l'application 'posts' et saisir le code suivant

# posts/models.py

from django.db import models
from django.contrib.auth import get_user_model

User = get_user_model()

class Post(models.Model):
    title = models.CharField(max_length=255)
    body = models.TextField()
    created_on = models.DateTimeField(auto_now_add=True)
    user = models.ForeignKey(User, on_delete=models.CASCADE)

À noter qu'avec chaque projet Django il y a un modèle User et des librairies d'authentification créer automatiquement. Le modèle User contient entre autre les champs: username, email, first_name, last_name et password.

Nous utilisons 'User = get_user_model()' afin de récupérer la référence vers ce modèle.

Enfin, ce fichier 'models.py' servira d'instruction à Django pour la création d'une base de donnée qui contiendra une table et des champs avec les mêmes définitions que dans ce fichier.

Pour créer la base de donnée, il faut créer un fichier de migration. Le fichier de migration est le plan, le "blueprint" de ce que doit contenir la base de donnée.

Django permet de créer automatiquement ce fichier de migration avec la commande suivante

$ python manage.py makemigrations

Une fois le fichier de migration créer, nous pouvons l'exécuter et Django va créer une base de donnée avec les instructions contenue dans la migration.

La commande pour lancer la migration est la suivante :

$ python manage.py migrate

Enfin, il est nécessaire de créer notre premier utilisateur. Django met à notre disposition une commande pour créer un super utilisateur

$ python manage.py createsuperuser

Cette commande vous demandera le username, email et password pour ensuite créer le user

Ajouter le modèle Post à l'admin panel

Pour utiliser le modèle Post à partir de l'Admin Panel de Django vous devez ajouter le code suivant

# posts/admin.py

from django.contrib import admin
from posts import models

admin.site.register(models.Post)

Visiter l'Admin Panel

Afin de s'assurer que tout ce que nous avons fait a fonctionné, lancer serveur et visiter l'Admin Panel

$ python manage.py runserver

La commande runserver va lancer un serveur Django

Pour accéder à l'Admin Panel, visitez la l'adresse : http://127.0.0.1:8000/admin/

Une page vous demandera username et password

Ensuite vous devriez voir une page avec les tables Groups, Users, et Posts

Comprendre la logique de Django rest-framework

Django rest-framework met à votre disposition des librairies qui permettent de créer un API de A à Z. Le rest-framework utilise une certaine logique qu'il vous faudra comprendre si vous désirez créer un API

Qu'est-ce que vous désirez créer comme API ?

L'API que nous désirons créer est en faite une interface pour lire, créer et modifier des articles (posts)

Voici les 6 actions et chemins que nous voulons créer:

• Lire la liste de tous nos articles : GET api/posts
• Lire un article en particulier: GET api/posts/1
• Créer un article : POST api/posts
• Modifier un article : PUT api/posts/1
• Modifier partiellement un article : PATCH api/posts/1
• Effacer un article : DELETE api/posts/1

Format d'échange de donnée

L'échange de donnée entre le backend et le frontend se fait sous format texte structuré au format JSON.

Le rest-framework prévoit donc une conversion entre le format Django et un format compatible JSON. Cette conversion utilise la classe Serializer.

Créer un Serializer

La première étape est donc de créer un serializer. Pour ce faire créer un fichier nommé serializers.py sous le dossier de l’application posts et ajouter ces lignes de code :

# posts/serializers.py
from rest_framework import serializers
from .models import Post


class PostSerializer(serializers.ModelSerializer):
    class Meta:
        model = Post
        fields = '__all__'

Voilà, ce n’est pas plus compliquer ! En faite, le gros du travail est fait par la librairie rest-framework. Ici, il suffit de mentionner quel modèle et quels champs nous désirons utiliser pour l'API.

À noter qu'a la place de 'all' vous auriez pu spécifier le nom de chaque champ voulu

fields = ['title', 'body']

Créer la view

Une fois le serializer de créer, rien ne nous empêche de créer l'API pour le modèle Post

ApiView vs ViewSet

Django REST Framework permet de créer la logique de notre API en utilisant deux techniques différentes :

ApiView

Utiliser la classe ApiView est la technique la plus longue pour créer un API, mais elle permet une très grande personnalisation. Si vous avez des besoins particuliers, le ApiView est votre option de choix.

ViewSet

Utiliser la classe ViewSet est la technique la plus rapide afin de créer un API basé sur un modèle Django lié à une base de donnée. La classe ViewSet va créer pour vous les 7 actions les plus souvent utilisées lorsque l'on crée un API: list, create, retreive, update, partial_update et destroy. C'est donc beaucoup plus rapide que créer chaque action manuellement comme avec les APIView. Par contre, si vous avez des besoins très particulier il ne sera pas possible de personnaliser votre API autant qu'avec les APIView

APIView ou ViewSet pour notre projet ?

Étant donné que nous allons créer un API basé sur un modèle Django et que celui-ci sera sans vraiment de personnalisation, j'ai choisi d'utiliser les ViewSet.

À partir du fichier views.py dans le dossier de l’application posts. Saisir le code suivant:

from rest_framework import viewsets

from .models import Post
from .serializers import PostSerializer


class PostViewSet(viewsets.ModelViewSet):
    serializer_class = PostSerializer
    queryset = Post.objects.all()

Encore une fois, vous avez une démonstration de la force de rest-framework. Il suffit de créer une view basé sur le 'ModelViewSet' et ensuite spécifier quel est le serializer et d'où proviendrons les données.

Avec ce simple code vous aurez accès au 6 actions tous héritées du ModelViewSets et de ses 6 méthodes équivalente : list, create, retrieve, update, partial_update et destroy

Une fois les 6 views disponible via PostViewSet il faut créer un chemin url pour chacune des 6 views.

Créer le chemin URL

Nous avons les views maintenant il ne reste plus qu'une étape et c'est de créer un chemin URL pour accéder à ces 6 actions.

Encore là pas besoin de créer 6 routes manuellement, rest-framework met à notre disposition la classe Router.

Créer un fichier urls.py sous le dossier de l'application posts

# posts/urls.py

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import PostViewSet

router = DefaultRouter()
router.register('posts', PostViewSet, 'post')

urlpatterns = [
    path('', include(router.urls)),
]

Ce code va créer les 6 chemin URL suivants:

• GET /posts (affiche la list view)
• GET /posts/ 1 (affiche le post avec id=1)
• POST /posts (create)
• PUT /posts/1 (update)
• PATCH /posts/1 (partial update)
• DELETE /posts/1 (Destroy post avec id=1)

La seule chose qui vous manque, c’est de relier ces routes à votre projet. Pour ce faire saisir le code suivant dans le fichier urls.py sous le projet config

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('posts.urls')),
]

Les routes créer sous posts/urls.py seront toutes utilisé sous l'url api/
Ex. api/posts

Enfin, il est temps de tester le tout en lançant le serveur

$ python manage.py runserver

Visitez ensuite l'adresse: http://127.0.0.1:8000/api

Cette page est créé automatiquement par le rest-framework afin de vous permettre de tester votre API.

Si vous cliquer sur l'API "posts". Une autre page s'ouvrira avec la liste de tous vos posts

Une fois que vous aurez créé un premier post, vous pourrez lire ce post en visitant son URL. (ex: api/posts/3)

Il est maintenant possible à l'aide de cette interface rest-framework de tester les 6 actions et chemin urls que nous avons créé plus tôt.

Fin de la première partie

C'est tout pour aujourd'hui. Dans la prochaine partie nous allons aborder l'authentification avec token et la protection de certaines actions/urls

Pour ne rien manquer cliqué Follow et/ou suivez-moi également sur Twitter : https://twitter.com/EricLeCodeur