Rest et Swagger

1. Introduction aux services web

Un service web est un outil logiciel permettant la communication entre plusieurs applications, en utilisant le protocole HTTP.

Lorsqu’un humain, le client, utilise le protocole HTTP, il effectue, via son navigateur, une requête POST pour soumettre des données ou une requête GET pour toute autre utilisation.

Dans le premier cas, le serveur valide les données reçues, puis renvoie généralement une réponse ou redirige le client vers une page consultable avec une requête GET.

Dans le second cas, le serveur va renvoyer du code HTML qui sera interprété par le navigateur pour construire une page qui, visuellement, donnera toutes les informations souhaitées à l’utilisateur.

Lorsque deux applications communiquent, elles échangent plutôt des données au format JSON et utilisent davantage de verbes HTTP pour distinguer les opérations à effectuer.

GET permet toujours au client de demander des données. Il communique une URL et le serveur lui renvoie une enveloppe JSON contenant des données ou une erreur.

POST permet cette fois-ci au client de créer une donnée. PUT sera utilisé pour remplacer une donnée (ou mettre à jour toutes les données) alors que PATCH sera utilisé pour mettre à jour partiellement une donnée (par exemple ne changer que le statut).

Enfin, le verbe DELETE servira à supprimer un ou plusieurs objets.

Nous nous attacherons à définir une URL représentative de la ressource manipulée, tandis que le verbe HTTP indiquera l’action effectuée sur cette ressource.

En ce qui nous concerne, l’URL /api-drf/game/ sera associée aux verbes suivants :

Et pour l’URL /api-drf/game/<pk>/, les verbes associés seront :

Lorsque le serveur répond, il renvoie lui aussi une enveloppe JSON.

Pour tester les services web...

1. Installer l’outil

Nous avons expliqué les grands principes d’un service web dans l’introduction de la partie précédente. DRF est une brique incontournable de Django pour en écrire. Mais il existe d’autres alternatives et, parmi elles, Django Ninja est extrêmement intéressant.

C’est un outil qui s’appuie sur l’excellent Pydantic (https://docs.pydantic.dev/latest/). Ce dernier permet de décrire précisément un modèle de données et de le valider, mais également d’en faire la conversion avec JSON, dans un sens ou dans l’autre.

Pour commencer, nous allons installer cet outil.

Pour cela, nous avons toujours le choix entre deux options.

Pour la première, il faut démarrer une console, puis taper la commande :

$ make bash 
$ poetry add django-ninja  

Normalement, le fichier pyproject.toml ainsi que le fichier poetry.lock sont tous deux mis à jour.

La seconde méthode consiste à rajouter directement les lignes suivantes dans pyproject.toml :

django-ninja = "^1.4.5"  

Puis, il faut utiliser la commande suivante pour générer un fichier poetry.lock cohérent avec ce dernier :

$ make lock  

Une fois ceci fait, quelle que soit la méthode, il faut reconstruire le conteneur :

$ make build  

Une fois que ceci est terminé, il n’y a pas besoin de modifier le fichier settings.py, mais il faut configurer les URL. Cela se fait en deux temps. Tout d’abord, on va créer un routeur dédié, dans un fichier project/ninja.py :

from ninja import NinjaAPI 
  
api = NinjaAPI()  

Puis configurer les URL à utiliser :

from .ninja import api 
  
urlpatterns = [ 
    ... 
    path('api-ninja/', api.urls), 
]  

Pour l’instant, nous avons créé, comme pour la partie précédente, un routeur qui ne fait strictement rien. Nous ajouterons les vues au fur et à mesure.

Vous devriez pouvoir constater la présence des vues ninja en faisant la commande suivante :

$ make show_urls  

Nous devrions voir ceci :

/api-ninja/  ninja.openapi.views.default_home  api-1.0.0:api-root ...