ZEP-02 : Elaboration d'une API

Welcome back !

devons-nous renommer le sujet de cette ZEP en ce sens d'ailleurs ?

Comme vous préférez. On peut aussi imaginer cette zep pour regrouper toutes les parties d'Api et un autre sujet a part pour chaque partie.

J'aime beaucoup ton idée. Je m'en charge dans la journée et je vous tiens au courant par ce topic.

Excellent travail de synthèse Andr0, merci.

Je pense que we're Good2Go (ahem…).

Pour les codes d'erreur manquant :

v0.4 : gestion du login :

POST :

• 400 si les headers Authbearer sont absents

• 403 si login failed

GET /membres/monprofil :

• 401 : pour un utilisateur non identifié qui essaie d'accéder à sa page de profil

Il manque un peu de détails sur le login d'ailleurs, il va falloir qu'on spécifie un peu plus le processus. Comment le token est retourné ? Est-ce-qu'on fournit un refreshToken ?

v0.5 :

Attention : "les informations se trouvent en paramètre de la requête" (c'est ptetre moi qui ai écrit ça à la base) c'est pas tout à fait juste : les paramètres se trouvent en contenu de la requêtes. Paramètres = queryParameters, Contenu = POST ou PUT content.

Pour le path : plutôt un PUT sur /membres/monprofil ou sur membres/id. PUT sur /membres devrait retourner une 405 (on ne modifie pas la liste à proprement parler).

Codes manquant :

• 400 si un champ n'est pas formaté comme attendu (400x à définir : email invalide, …) s'inspirer de la gestion d'erreur déjà présente sur la page de profil.

• 401 si non authentifié

• 403 si essai de modifier un profil autre que le sien

• 404 si id du membre n'existe pas

La ZEP-17 a été crée. Toutes les discussions sur l'API des membres se fera maintenant sur ce nouveau sujet.

Javier, j'y ai intégré tes dernières remarques.

Le premier post de ce topic a été modifié pour rendre la ZEP-02 générique à toute l'API et liste toutes les ZEP spécifiques pour chaque ressource (pour l'instant, seulement les membres).

La ZEP-17 est donc en route mais j'encourage n'importe quel membre qui veut contribuer à l'élaboration de l'API à créer une nouvelle ZEP sur une nouvelle ressource pour en rédiger ses spécifications et la mener au statut d'accepté auprès des développeurs et du staff de Zeste de Savoir !

Il faut juste penser à venir notifier de leurs créations sur ce topic pour pouvoir les référencer avec les autres.

(Sorry double post)

Ceux qui se tiennent un peu au courant de l'avancement de l'API de ZdS le savent, la ZEP 17 (consacré à l'API des membres) vient de passer au statut "Validation" et ne devrait pas tarder à passer au statut suivant (à savoir, "Accepté") pour commencer son développement.

Cela ne m'empêche pas de déjà regarder techniquement comment va se passer la mise en oeuvre de cette API. J'aimerais profiter de ce topic (donnons lui un peu d'utilité) pour discuter de l'implémentation concrète derrière toutes nos discussions et nos débats.

Par où commencer …

J'ai l'impression que le code actuel dans le back-end n'est pas du tout prévu pour accueillir une API sans avoir une répétition de code monstrueuse. Je m'explique : Nous avons commencé par un module simple (et heureusement), le module des membres. Ce module possède les fichiers suivants :

• admin.py : Inutile dans le cadre de l'API. Ca permet d'avoir une interface admin pour les membres.
• decorator.py : Inutile dans le cadre de l'API. Il possède une seule méthode pour gérer un utilisateur sanctionné.
• factories.py : Inutile dans le cadre de l'API. Il est utilisé pour les tests du module.
• forms.py : Inutile dans le cadre de l'API. Il est utilisé pour construire des formulaires et les renvoyer dans les templates.
• models.py : Toutes les classes du modèle qui regroupent un certain nombre de requêtes vers la base pour récupérer des informations relatives aux membres. Ce fichier sera très largement utilisé dans le cadre de l'API.
• urls.py : Regroupe toutes les routes vers les vues. Il sera réutilisé pour rajouter toutes les routes de l'API.
• views.py : Il est utilisé pour répondre aux requêtes utilisateurs et utiliser un peu près toutes les classes des fichiers précédents pour construire les vues à l'utilisateur.

Mon objectif serait de réutiliser tout ce qui se trouve dans le fichier views.py puisque ce sont dans ses méthodes qu'il y a quasi (oui, parce que parfois elles sont dans les classes du modèles …) toutes les règles métiers. Mais il y a plusieurs autres problèmes :

• Dans une utilisation poussée de Django Rest Framework, il n'est pas possible d'utiliser les méthodes contenues dans views.py puisque des classes mères spécifiques sont utilisées.
• Dans une utilisation moins poussée de Django Rest Framework, il devrait être possible de réutiliser les vues de views.py mais les méthodes ne seront plus du tout maintenable !
• L'état actuel des méthodes de views.py sont déplorables. Il y a des requêtes en base des classes des modèles du module et d'autres modules dans les méthodes et de la logique métier. Un refactoring en profondeur semble nécessaire !
• Aucune utilisation de bonnes pratiques Django comme les managers ou les adapteurs pour répartir les différentes responsabilités et avoir un code plus maintenable et plus simple (il me semble) à utiliser pour l'API.

Je ne suis pas un expert Django. Si ça se trouve, je suis complètement à côté de mes pompes mais les résultats de mes recherches de cette soirée font peurs et remettent en cause la mise en oeuvre à plus ou moins moyen terme d'une API, même pour un petit module comme les membres.

Django Rest Framework propose 2 façon d'écrire son API.

• ajouter des décorateurs du genre @api_view(['GET', 'POST']) sur les méthodes des views.py. Ce qui est très souvent fait quand on passe écrit une API après avoir fait son site.
• restructurer complètement le fichier views.py ce qui implique, quand on part d'une base de code, de dupliquer le code et donc de maintenir pendant un moment deux morceaux de code. Pour la simple et bonne raison que cette structure ne s'accorde pas toujours avec la structure Django elle même.

C'est donc aussi simple que ça. Soit on part sur la méthode 1 et on aura probablement quelques fonctions avancées de Django Rest Framework qui nous manqueront (je doute qu'on en ait le besoin), soit on part sur la méthode deux et il faudra maintenir 2 codes parfaitement identique à chaque évolution.

Ta première solution correspondait à ma seconde solution et ta deuxième solution à mes constats du code actuel.

Donc oui, j'avais déjà vu dans le décorateur @api_view une solution intéressante pour nous mais pour illustrer le problème, prenons un exemple :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

def details(request, user_name):
    """Displays details about a profile."""

    usr = get_object_or_404(User, username=user_name)
    try:
        profile = usr.profile
        bans = Ban.objects.filter(user=usr).order_by("-pubdate")
    except SiteProfileNotAvailable:
        raise Http404

    # refresh moderation chart

    dot_chart = pygal.Dot(x_label_rotation=30)
    dot_chart.title = u"Messages postés par période"
    dot_chart.x_labels = [
        u"Dimanche",
        u"Lundi",
        u"Mardi",
        u"Mercredi",
        u"Jeudi",
        u"Vendredi",
        u"Samedi",
    ]
    dot_chart.show_legend = False
    dates = date_to_chart(profile.get_posts())
    for i in range(0, 24):
        dot_chart.add(str(i) + " h", dates[(i + 1) % 24])
    img_path = os.path.join(settings.MEDIA_ROOT, "pygal")
    if not os.path.isdir(img_path):
        os.makedirs(img_path, mode=0o777)
    fchart = os.path.join(img_path, "mod-{}.svg".format(str(usr.pk)))
    dot_chart.render_to_file(fchart)
    my_articles = Article.objects.filter(sha_public__isnull=False).order_by(
        "-pubdate").filter(authors__in=[usr]).all()[:5]
    my_tutorials = \
        Tutorial.objects.filter(sha_public__isnull=False) \
        .filter(authors__in=[usr]) \
        .order_by("-pubdate"
                  ).all()[:5]

    my_tuto_versions = []
    for my_tutorial in my_tutorials:
        mandata = my_tutorial.load_json_for_public()
        my_tutorial.load_dic(mandata)
        my_tuto_versions.append(mandata)
    my_article_versions = []
    for my_article in my_articles:
        article_version = my_article.load_json_for_public()
        my_article.load_dic(article_version)
        my_article_versions.append(article_version)

    my_topics = \
        Topic.objects\
        .filter(author=usr)\
        .exclude(Q(forum__group__isnull=False) & ~Q(forum__group__in=request.user.groups.all()))\
        .prefetch_related("author")\
        .order_by("-pubdate").all()[:5]

    form = OldTutoForm(profile)
    oldtutos = []
    if profile.sdz_tutorial:
        olds = profile.sdz_tutorial.strip().split(":")
    else:
        olds = []
    for old in olds:
        oldtutos.append(get_info_old_tuto(old))
    return render_template("member/profile.html", {
        "usr": usr,
        "profile": profile,
        "bans": bans,
        "articles": my_article_versions,
        "tutorials": my_tuto_versions,
        "topics": my_topics,
        "form": form,
        "old_tutos": oldtutos,
    })

Cette méthode dans views.py récupère un membre en fonction de son username. Ceci correspond donc (quasiment puisque nous nous basons sur l'identifiant) à la version 0.0 de notre API des membres comme décrit dans la spec que nous avons rédigé pour la ZEP 17.

Tu vois les problèmes où je les énumère ?

• Cette méthode récupère déjà les tutoriels et les articles du membre (hors scope de l'API des membres).
• Il y a du rendu dans la méthode, notamment avec dot_chart et surtout à la fin avec la méthode render_template.
• Des requêtes brutales des articles et des tutoriels.
• Si nous voulons supporter l'API dans cette méthode, elle va très certainement triplé de volume comme toutes les autres méthodes du fichier.

Si tu me dis qu'annoter @api_view cette méthode suffira, je ne te croirais pas. Ce n'est donc pas "aussi simple que ça".

Juste une question : pourquoi on ne crée pas un fichier api.py? Non parce que là on va se retaper des fichiers de 10 000 lignes.

Actuellement, quasi toutes les règles métiers sont dans les méthodes views.py. Ca va donc demander de maintenir deux fichiers (api.py et views.py) avec quasiment le même code. C'est ce que disait firm1 dans son second point.

je connais pas Django mais les deux approches que vous décrivez me paraissent complètement folles.

C'est pas possible d'avoir deux contrôleurs, l'un qui retourne un template, l'autre qui retourne du "pur" JSON, et que les deux soient branchés sur un même service ??

Quel que soit le framework que j'ai utilisé j'ai absolument toujours retrouvé cette façon de faire. Qu'on l'appelle Manager, Service ou quoi, cette partie du code est toujours "à part".

Je vous laisse trancher pour la bonne solution, mais c'est pas possible de découper comme ça ?

Je ne suis pas un expert Django non plus mais d'après des recherches rapides, si. C'est ce que je décris dans mon dernier point :

• Aucune utilisation de bonnes pratiques Django comme les managers ou les adapteurs pour répartir les différentes responsabilités et avoir un code plus maintenable et plus simple (il me semble) à utiliser pour l'API.

Rien n'est fait nul part dans le projet à l'heure où j'écris ces lignes.

Ah mais ce n'est pas un problème. Javier vient justement d'indiquer la solution. Il suffit de les transformer tous en service. Dans la même veine que ce qui est fais ici pour les forums ou là pour les MPs.

Nous sommes d'accord alors. Nous sommes donc aussi d'accord pour dire que l'API ne peut pas commencer avant un refactoring de chaque module. Ca va être fun.

Question à ce sujet : j'ai aussi regardé récement le code, et seule des fonctions sont utilisées comme vues. Pourquoi ne pas avoir utilisé des ClassBasedView ? Cela permet par exemple d'utiliser des Mixin pour l'API, de factoriser à mort le code (plus de if request.type == POST) et de bien simplifier le tout.

Du coup, quitte à refactoriser le code, pourquoi ne pas utiliser ce genre de vues ?

C'est axactement ce qu'il faudrait faire. J'ai déjà un peu commencé sur le module des membres mais ça prend du temps, chose dont je ne dispose pas beaucoup en ce moment.

Un petit coucou par ici pour savoir comment les choses avancent. Je n'ai pas vu de branche dédiée à la ZEP-02 sur le dépot GitHub, c'est normal ou c'est juste un oubli ?

Il n'y aura pas de branches ZEP-02 mais ZEP-17, je ne suis même pas sûr qu'il faut une branche à part (je ne l'ai pas fais) puisque la ZEP est bien versionnée et peut se faire par itération. Par contre, je n'ai personnellement pas le temps de faire le refactoring pour l'instant, comme indiqué dans mon précédent message.

je ne suis même pas sûr qu'il faut une branche à part (je ne l'ai pas fais) puisque la ZEP est bien versionnée et peut se faire par itération

L'idée d'avoir une branche a coté, c'est de permettre aussi à plusieurs personnes de travailler sur une itération de la ZEP, en même temps. Quelqu'un pourrait pousser la doc, quelqu'un d'autre les tests, quelqu'un d'autre encore une partie de la refacto, etc.

Si tout le monde fait sa branche dans son coin ce n'est pas viable, car on ne pourra pas pousser sur le dépôt par exemple une PR qui fait de la doc pour un module qui n'existe pas encore. D'ou l'idée de centraliser toute la ZEP-17 sur une branche du dépot officiel pour faire participer le plus de personne étant donné que la spec est déjà formalisée

Ok, je comprends mais il reste un problème. Le refactoring nécessaire pour la ZEP ne devrait pas être lié au développement de cette ZEP, et donc dans sa branche. Et très sincèrement, c'est un travail énorme de refactorer tout le projet pour pouvoir utiliser l'existant dans le développement de l'API.

D'après ce que tu dis, c'est pourtant un pré-réquis de la ZEP. Donc si le pré-requis n'est pas fait, la ZEP non plus. ça peut tourner en rond pendant longtemps, et au final on risque d'abandonner parce que c'es trop gros.

A mon avis, il faut penser communautaire. Pas forcément se dire que tout sera fait par une seule personne, mais justement que tout le monde puisse participer (aussi minime soit les apports) au développement. Ceci passe donc par une ouverture et une publication fréquente dès qu'on a quelque chose. ça permet aux autres de suivrent, et a certaines personnes de pouvoir apporter une aide ponctuelle sur certains points.