ZEP-26 : Rendre les urls plus cohérentes

Contexte

Actuellement, les urls ne sont pas cohérentes entre-elles.

Par exemple, pour voir les sujets du forum que j'ai créé il faut passer par https://zestedesavoir.com/forums/sujets/membre/273/ mais pour voir les messages que j'ai créé il faut aller sur https://zestedesavoir.com/forums/messages/273/. Dans un cas il y a membre/ mais pas dans l'autre !

Si l'on veut voir les tutoriels, il faut aller sur https://zestedesavoir.com/tutoriels/ mais pour les galeries c'est https://zestedesavoir.com/galerie/. Dès fois il y a un "s", dès fois il n'y en a pas !

Dernier exemple : les urls des sujets du forum contiennent un tiret comme ça "-" mais certaines urls contient un tiret comme ça "_" ( https://github.com/zestedesavoir/zds-site/blob/dev/zds/member/urls.py#L28 ) ! Certaines urls sont même en anglais ( https://github.com/zestedesavoir/zds-site/blob/dev/zds/member/urls.py#L43 ) !

Il y a aussi des différences avec les urls de l'API.

Objet de la proposition

Il faut alors :

• établir des règles précises sur comment sont créées nos urls ;
• prévenir les développeurs (en particulier ceux développant des ZEPs touchant aux urls) de ces règles ;
• faire la liste des changements à faire pour les urls actuelles ;
• lors du passage en v2.0 (ou une autre version ?), modifier les urls existantes pour qu'elles respectent ces règles (en n'oubliant pas les redirection).

Formation des urls

Nos urls devront être :

• en français ;
• en minuscule ;
• composées du tiret du milieu - et non pas celui du bas _.

Faut-il faire une ZEP ?

je suis tenté de dire "oui" pour deux raisons :

• on est dans le cadre d'une vraie spécification
• il y a des "dommage collatéraux" : quelles sont les URLs qui une fois modifiées seront redirigées? Quelles sont celles qu'on oublie? Est-ce qu'on met des doublons? Est-ce qu'on met un "/v2/" devant les nouvelles url?
• si ces différences sont apparus c'est que les avis des membres sont multiples, il va falloir en débattre.

Je suis également d'avis que remettre un peu d'ordre là dedans serai profitable

Ceci dit, on peut partir des constatations:

• Nos urls sont en français (et dès lors, doivent le rester)
• Il semble qu'il y aie un consensus pour dire qu'une URL ressemble à https://zestedesavoir.com/<module>/<le reste>/
• Rappelons également que changer une URL est plus "cosmétique" (mais nécéssaire) qu'autre chose, puisque avec Django, aucune URL n'est codée en dur. Cette ZEP peut donc paraitre longue à implémenter le cas échéant, mais non

Bonne idée

Juste une remarque : c'est un domaine que je connais très très mal mais j'essaie d'y faire attention quand je bricole des trucs comme ça : pendant le transfert, attention au SEO (et aux bookmarks, éventuellement).

Va falloir passer par une phase où le serveur renvoie des 301 sur certaines requêtes, non ?

Oui, mais Django peut gérer ça. D'ailleurs je crois qu'on l'a déjà fait avant !

Je plusseoie Javier : le problème est identifié depuis longtemps (avant la v1.0 en fait, y'a un ticket Github qui en parle) mais n'a jamais été corrigé à cause du problème des URLs existantes.

quelles sont les URLs qui une fois modifiées seront redirigées?

Pour moi, toutes sauf celles réservées au Staff. Après, on peut aussi les inclure si vous voulez, ça demande pas énormément de boulot…

Est-ce qu'on met des doublons?

Je suis contre les doublons mais on peut éventuellement imaginer des raccourcis qui redirigeraient vers la bonne page (sauf si ça affecte le SEO).

Est-ce qu'on met un "/v2/" devant les nouvelles url?

Je suis pas pour, ce serait source d'erreur, surtout si ce n'est présent que sur les nouvelles urls…

Du coup, je propose de :

• établir des règles précises sur comment sont créées nos urls ;
• prévenir les développeurs (en particulier ceux développant des ZEPs touchant aux urls) de ces règles ;
• faire la liste des changements à faire pour les urls actuelles ;
• lors du passage en v2.0 (ou une autre version ?), modifier les urls existantes pour qu'elles respectent ces règles (en n'oubliant pas les redirection). que les nouveaux modules de l'API respectent ces règles.

Ces trois points vous conviennent ?

Concernant les règles sur la création des urls, AMHA on peut avoir comme base que nos urls sont :

• en français (excepté l'API ?) ;
• en minuscule ;
• composées du tiret du milieu - et non pas celui du bas _.

À noter que ce sera probablement implémenté tel que recommandé ici dans la ZEP-12, comme ça on va plus vite.

Du reste, il faut distinguer plusieurs types d'URL: les "accesseurs" et les "modifieurs". Pour ces dernier, il y a des mots clés bien spécifiques, qui sont en général des infinitifs, du genre /<module>/<mot-clé>/<le reste>, où <mot-clé> peut être modifier, éditer, supprimer et ainsi de suite. Il serait bien de voir quels sont ces "mots clés" et se mettre d'accord sur qui fait quoi partout. Intéréssant aussi, serait de ce mettre d'accord sur ce que j'appelle <le reste> dans ces urls de modifications: par exemple, une url du type /tutoriel/modifier/extrait/ existe, mais on a aussi /mp/message/editer/. On a dans ces deux exemples ce que je viens de dire : "modifier"/"editer" et l'ordre qui n'est pas le même ("éditer" viens à la fin dans le second cas). À noter que le premier cas est plus simple pour différente raison à implémenter.

Sous-débat: est-ce qu'il faut une URL différente pour les requêtes GET/POST ?

Je suis pour l'idée de revoir les URLs qui sont catastrophiques. Les décisions prises par ce débat m'intéresseront puisque je suis en train de faire le refactoring du module des MPs où je change déjà les URLs. Elles ne sont pas publiques, cela ne pose donc pas de problème.

Voici comment je comptais modifier les URLs :

• /mps/ : Liste les conversations privées. Précédemment : /mp/.
• /mps/quitter/ : Quitte une liste de conversations privées. Précédemment : /mp/.
• /mps/nouveau/ : Créé une nouvelle conversation privées. Précédemment : /mp/nouveau/.
• /mps/{pk}/editer/ : Edite une conversation privées. Précédemment : /mp/editer/.
• /mps/{pk}/editer/participants/ : Edite une conversation privées pour ajouter des participants. Précédemment : /mp/ajouter/.
• /mps/{pk}/quitter/ : Quitte une conversation privées. Précédemment : /mp/quitter/.
• /mps/{pk}/messages/ : Liste tous les messages paginés d'une conversation privée. Précédemment : /mp/{topic_pk}/{topic_slug}/.
• /mps/{pk}/messages/nouveau/ : Ajoute une réponse dans une conversation. Précédemment : /mp/messages/nouveau/.
• /mps/{pk}/messages/{pk}/editer/ : Edite un message d'une conversation privée. Précédemment : /mp/messages/editer/.

Donc qu'est-ce que j'ai fais comme modification ? J'ai mis au pluriel les ressources comme c'était déjà le cas dans les autres modules ; J'ai rendu explicite ce qui devait être explicite ; J'ai reformulé certaines URLs pour se rapprocher des "standards".

Je ne sais pas ce que vous en pensez mais je trouve ça plus cohérent.

Sous-débat: est-ce qu'il faut une URL différente pour les requêtes GET/POST ?

Je ne suis pas pour. D'abord parce que techniquement, cela va nécessiter qu'une classe aura plusieurs responsabilités et, fonctionnellement, cela n'apporte rien sauf de la complexité.

en français (excepté l'API ?) ;

Les URLs de l'API sont en français pour rester cohérent avec les URLs du site.

Un des défauts de ce qu'a choisi Andr0 est l'utilisation de "editer" et "nouveau". Il faudrait choisir "editer" et "creer" ou "edition" et "nouveau", non ?

Effectivement, ce n'est pas bête et j'aurais tendance à privilégier les verbes.

Pour faire le lien avec l'API, on parle souvent de "verbe HTTP" (un anglicisme ?), et si on regarde par rapport à ce que tu donnes on voit clairement la correspondance entre un verbe à l'infinitif et les méthodes HTTP correspondantes (créer = POST, éditer = PUT, supprimer (quitter) = DELETE).

Donc à fond pour des verbes à l'infinitif qui représentent les "verbs" HTTP.

Je propose cette deuxième révision :

Contexte

Actuellement, les urls ne sont pas cohérentes entre-elles.

Par exemple, pour voir les sujets du forum que j'ai créé il faut passer par https://zestedesavoir.com/forums/sujets/membre/273/ mais pour voir les messages que j'ai créé il faut aller sur https://zestedesavoir.com/forums/messages/273/. Dans un cas il y a membre/ mais pas dans l'autre !

Si l'on veut voir les tutoriels, il faut aller sur https://zestedesavoir.com/tutoriels/ mais pour les galeries c'est https://zestedesavoir.com/galerie/. Dès fois il y a un "s", dès fois il n'y en a pas !

Dernier exemple : les urls des sujets du forum contiennent un tiret comme ça "-" mais certaines urls contient un tiret comme ça "_" ( https://github.com/zestedesavoir/zds-site/blob/dev/zds/member/urls.py#L28 ) ! Certaines urls sont même en anglais ( https://github.com/zestedesavoir/zds-site/blob/dev/zds/member/urls.py#L43 ) !

Il y a aussi des différences avec les urls de l'API.

Objet de la proposition

Il faut alors :

• établir des règles précises sur comment sont créées nos urls ;
• prévenir les développeurs (en particulier ceux développant des ZEPs touchant aux urls) de ces règles ;
• faire la liste des changements à faire pour les urls actuelles ;
• lors du passage en v2.0 (ou une autre version ?), modifier les urls existantes pour qu'elles respectent ces règles (en n'oubliant pas les redirection). que les nouveaux modules de l'API respectent ces règles.

Formation des urls

Nos urls devront être :

• en français ;
• en minuscule ;
• composées du tiret du milieu - et non pas celui du bas _.

Je trouve que ça ne fait pas sens de mettre les URL en Français : le projet a été internationalisé en partie, les objets sont écrits en anglais, etc. Certes, tout n'est pas en anglais, mais pourquoi ne pas essayer d'y tendre pour la v2 ? ZdS est devenu un gros CMS qui propose des fonctionnalités intéressantes, et je pense qu'il peut attirer des développeurs non-francophone.

Ça mérite probablement un sujet à part (ou d'en remonter un), mais je trouve que la discussion vaut le coup, et personnellement je pense qu'une décision ferme devrait être prise dans les meilleurs délais pour s'économiser du travail (et de même pour d'autres sujets…).

ZdS est devenu un gros CMS qui propose des fonctionnalités intéressantes

Très honnêtement, je ne pense pas. Zeste de Savoir (l'outil) est d'abord et avant tout l'application qui fait fonctionner Zeste de Savoir (le site). Le fait qu'on le mette à disposition et qu'on soit plutôt gentils avec ceux qui veulent le reprendre n'est qu'un plus, ce n'est pas le but du projet et ça ne l'a jamais été.

C'est très important parce que ça fait de nous les créateurs d'un site et non les développeurs d'un outil. Ce n'est pas du tout la même gestion du projet. Et ça implique aussi un certain taux d'égoïsme : les décisions on les prends d'abord pour le site Zeste de Savoir ; et s'il y a conflit entre l'intérêt de Zeste de Savoir (le site) et une solution plus générique, c'est le premier qui prime.

On pourrait se poser la question de devenir éditeurs d'une solution, mais ça nécessite une décision de l'association en plus de changements majeurs dans l'organisation.

L'une des conséquences est qu'on est un site francophone et que donc ça paraît logique que les URLs soient en français. Si un fork veut décider du contraire, très honnêtement avec Django c'est pas très compliqué à modifier. Chiant, mais pas compliqué.

Ce débat, nous l'avons déjà plus ou moins eu à l'époque et je faisais parti des personnes qui voulait passer le plus de choses en anglais. Le code, les commentaires, etc sont en anglais et c'est une bonne chose mais les URLs doivent rester en français selon moi. Juste pour avoir une certaine cohérence.

Actuellement, nous nous basons beaucoup sur les slug et ils sont en français. Si tout le reste de l'URL est en anglais et certaines parties en français, cela ferait vraiment bizarre. Nous aurions quelque chose comme : zestedesavoir.com/forums/topic/2558/zep-26-rendre-les-urls-plus-coherentes. Bien que "topic" est un mot de notre langage courant ici, cela ne l'est pas pour "tutorial" par exemple.

C'est très important parce que ça fait de nous les créateurs d'un site et non les développeurs d'un outil.

Vu comme ça, évidemment.

A mon avis, on peut trouver plusieurs schémas d'urls :

• /<module>/, par exemple "/tutoriels/" ;
• /<module>/<objet>/, par exemple "/membres/paramètres/" ;
• /<module>/<sous-module>/, par exemple "/forums/notifications/" ;
• /<module>/<sous-module>/<action>/, par exemple "/forums/sujet/nouveau/" ;
• /<module>/<sous-module>/<action>/<objet>/, par exemple "/galerie/image/editer/<identifiant-image>/<slug-image>/" ;
• /<module>/<sous-module>/<sous-sous-module>/<objet>, par exemple "/forums/sujets/membre/<identifiant-utilisateur>/" ;
• /<module>/<action>/, par exemple "/galerie/nouveau/" ;
• /<module>/<action>/<objet>/, par exemple "".

Il y en a d'autres que je n'ai pas listé. C'est tellement le bazard que je peine à m'y retrouver !

Chaque partie devrait respecter certains critères :

• <module> doit être un nom au pluriel ;
• <action> doit être un verbe à l'infinitif ;

Que doit-être <objet> ? Un identifiant, un slug ou les deux ? 123/, super-tuto/ ou 123/super-tuto/ ?

Que doivent-être <sous-module> et <sous-sous-module> ? Actuellement c'est assez vague, il y a "parametres", "profil" ou encore "connexion".

Que fait-on du module de recherche qui est accessible via /rechercher/. Or, ce n'est pas un nom au pluriel mais un verbe. Est-ce qu'on doit le transformer en /recherches/ ou doit-on faire une exception ?

Il faudra choisir si l'on fait une exception pour /membres/connexion/ et /membres/inscription/ car elles ne correspondent pas à <action> qui doit être un verbe à l'infinitif.

Je me rend compte en parcourant le code du dépôt (les fichiers zds/urls.py et zds/<module>/urls.py) que presque aucune url ne ressemble aux autres, surtout quand elle commence par /<module>/<sous-module>/. Il y a tellement de cas à gérer que l'on devra faire des exceptions ou laisser du lest ! Voici un pad contenant les urls des galeries et des forums pour vous faire une idée du nombre de cas à gérer.

Singulier ou pluriel pour les URLs ? Avec quels arguments ?

Pluriel parce que toutes nos URLs sont déjà au pluriel. Ça, c'est l'argument le plus simple, et à vrai dire le plus ridicule (un peu fondamentaliste sur les bords, là). En plus, c'est même pas vrai, parce que c'est le cas partout, sauf pour les galeries (mais comme j'ai une PR refacto sur le feu, je peux discrètement changer ça si ça vous amuse).

Plus sérieusement. Le pluriel a pour moi plus de sens dans des cas comme les articles et tutos, ou /articles/ te renvois sur … Une liste d'articles. De là à dire "pluriels partout", il n'y a évidement qu'un pas. Reste à se demander si /articles/12/machinchose/ a toujours du sens dans le contexte.

J'en profite par ailleurs pour dire que pour la ZEP-12 (voir ici), on a instinctivement choisi le format <module>/<action>/<objet>/. Pourquoi ? Parce que maintenant qu'on c'est débarrassé des pk dans les URLs, celles-ci devienent quelques peu imprévisibles, donc il faut absolument que <objet> soit à la fin. Celui qui veut nous faire changer ça va devoir nous donner un moyen de faire autrement

Plus sérieusement. Le pluriel a pour moi plus de sens dans des cas comme les articles et tutos, ou /articles/ te renvois sur … Une liste d'articles. De là à dire "pluriels partout", il n'y a évidement qu'un pas.

Tous nos modules (tutoriels, articles, messages privés, forums, galeries, membres et pages) renvoient une liste excepté le module pour la recherche !

Reste à se demander si /articles/12/machinchose/ a toujours du sens dans le contexte.

On pourrait faire /articles/ qui renvoie la liste des articles et /article/machinchose/ qui renvoie un article. Mais personnellement il m'arrive souvent sur les sites web d'enlever le /machinchose/ et de tomber sur la bonne page et non pas une 404.