ZEP-02 : Elaboration d'une API

Deux remarques à prendre en compte dans la rédaction de la ZEP selon moi :

1. Est-ce que les APIs ont un mode de fonctionnement différentiel : "renvoie moi tous les tutoriels publiés APRES telle date". Auquel cas en plus des URL d'appel des primitives il faut spécifier les paramètres

2. Est-ce-que certaines APIs sont contextuelles (les messages privés) ou est-ce-qu'on se cantonne à des APIs publiques. Dans le premier cas il faut réfléchir à l'authentification (OAuth a été évoqué). A mon avis en v1 il faut faire du "tout public" pour valider le concept.

On pourra pas se passer de l'authentification a moyen terme sinon tu enlève toute possibilité d'écriture, non ?

Je ne vois absolument pas en quoi faudrait filtrer les détails. Une API implique la même chose que pour l'app en elle-même : tu n'es pas connecté ? T'as un minimum de détails en effet. Type la liste de posts d'un topic auquel tu as accès en étant déconnecté. Etc. Tu es connecté ? La liste auquel tu as accès.

Il n'y a vraiment que le droit à prendre en filtre, finalement.

Mais je suis aussi également pour avoir un truc qui fasse de la lecture / écriture, quitte à le sortir module par module… Et pourquoi pas derrière avoir une full app qui ne travaille qu'en API, justement, via des tokens etc. Bref, du REST en somme.

Au passage je pense qu'on pourrait rajouter une api mappé sur notre markdown, permettant a partir d'un markdown donné de produire le html correspondant.

Supposont que ce soit le cas, il faudrait tout de meme qu'en lisant la zep on comprenne quels sont les types d'autorisations possible et la sortie qu'ils peuvent recevoir.

Ceci dit corcernant la vie privée, je n'ai pas trop reflechi, mais l'exemple qui me viendrait tout de suite a l'esprit serait que, normalement ça ne pose aucun probleme sur un forum que tes messages soient public, mais si l'API offre par exemple la liste des messages postés par un membres, il serait facile pour une application externe de constituer un graphe sur lequel, pour chaque membre on arrive a savoir a quels sont ses horaires habituels de posts dans la semaine. Je ne sait donc pas si tout le monde aimerait que ce genre de recoupement soit fait et public. Je n'ai aucune idee de la portée juridique de ce genre de regroupement.

Pareil pour les emails. Ceux qui autorisent sans le savoir la visibilité de leur emails pourrait constituer une cibles pour n'importe quelle agence de publicité.

Bref, il faut reflechir a chaque info et voir vraiment la portée et les cas d'usage des données qu'on mets a disposition.

Ceci dit corcernant la vie privée, je n'ai pas trop reflechi, mais l'exemple qui me viendrait tout de suite a l'esprit serait que, normalement ça ne pose aucun probleme sur un forum que tes messages soient public, mais si l'API offre par exemple la liste des messages postés par un membres, il serait facile pour une application externe de constituer un graphe sur lequel, pour chaque membre on arrive a savoir a quels sont ses horaires habituels de posts dans la semaine. Je ne sait donc pas si tout le monde aimerait que ce genre de recoupement soit fait et public. Je n'ai aucune idee de la portée juridique de ce genre de regroupement.

Bah je pense que c'est un faux problème. Ce sont des données public, il faut se rendre compte qu'il est possible de le faire. Car de toute façon c'est déjà le cas, ces informations sont déjà sur le site et il suffirait de faire un tout petit crawler rapide pour déjà pouvoir constituer ce genre de choses. Je ne pense pas que la non possibilité de faire ça via une API empêchera les gens qui veulent le faire de le réaliser.

la liste des messages postés par un membres

Ce genre de chose n'a rien à faire dans une API. A la limite les 10 derniers messages. A la limite, tous les messages du membre connecté, mais publiquement c'est le genre de chose qui n'a aucun intérêt et qui se révèle dangereux comme tu l'expose.

Le problème des API en écriture, c'est que ça va créer beaucoup de duplicata de code.

L'idéal c'est soit :

• de refaire tout le front en dynamique client (avec AngularJS, Backbone ou Ember, enfin un MVW/C front) + PhantomJS ou ce genre de chose pour délivrer des fichiers statiques au besoin
• de brancher le code actuel sur l'API pour factoriser le code

La deuxième solution étant la plus simple, il s'agit simplement de déplacer/reanier légèrement du code, et de faire des appels à des fonctions à d'autres endroits.

Ma vision des choses est qu'il faut revoir le code pour le rendre réellement orienté objet + MVT, avec tout ce que ça implique : un nouveau message ? Ok, on crée une nouvelle instance de l'objet/entité message, en lui passant les divers paramètres qui vont bien. Un nouveau tuto ? Même procédé.

Tout le code métier doit être contenu dans les modèles. Les vues ne doivent qu’appeler les templates en leur balançant le résultat des calculs effectués par les modèles.

Si on ne fait pas attention à ce que l'on fait, on va se retrouver avec deux versions du code à maintenir partout.

PS : Il faut faire la refacto globale du projet avant de s'attaquer à toute amélioration de ce type (ici, API) car c'est prioritaire selon moi pour ne pas avoir à refacto encore plus de code.

Tout ce que tu dis Alex est défendable (quoique moi j'ai peur que se lancer dans un tel refacto nous prenne beaucoup de temps et bloque des milliers de choses le temps que ce soit fait) mais dans tous les cas ce n'est pas le prob d'une ZEP : Ici on doit arriver à un cahier des charges sur ce qu'est censé faire cette API, pas comment la technique va devoir s’adapter à ça.

Par ailleurs, on peut imaginer que l'implémentation de l'API pourra se faire en parallèle de certaines améliorations. Je pense par exemple à la ZEP-XX (à venir) sur l'évolution du système des tutoriels et articles, pour permettre de créer des tutos de taille intermédiaire (plusieurs chapitres sans une distinction par parties), ou de faire de PR sur le contenu : ça peut s'implémenter dans la continuité de l'effort. Étant donné que le code métier va bouger, faire coller son interface publique à une API ne nous demandera pas beaucoup plus de boulot.

Ma vision des choses est qu'il faut revoir le code pour le rendre réellement orienté objet

Je me méfie du "réellement objet". C'est une notion assez vague derrière laquelle on peut mettre tout et n'importe quoi. A fortiori en Python.

Quoi qu'il en soit, c'est effectivement des considérations hors-sujet dans une spec : encore une fois, la ZEP est rédigée avant tout pour traduire une évolution désirée par la communauté. Le comment, ça vient dans un troisième temps après le quoi et le pourquoi.

C'est bien pour cela que je voudrais (je n'ai pas d'avis n'ayant pas les compétences juridiques adéquates) qu'on précise ça clairement.

Peux-tu developper ce point ? Le duplicata de code tu l'imagine entre quoi et quoi ?

Ce qui signifierait que ce soit le framework front qui constitue la surcouche REST. Pourquoi pas, mais qu'en est-il des performances de delivery ?

Une chose à la fois. On s'assure d'abord que l'API est stable (ça peut prendre au moins 2-3 mois rien que pour stabiliser), et ensuite on effectue la migration au fur et a mesure de site par dessus l'API. Le duplicata de code temporaire n'a jamais tué personnes, par contre les merge trop hatifs entrainent souvent des regressions.

Je ne pense pas que le paradigme Orienté Objet devrait être un objectif à atteindre.

Je ne pense pas non plus qu'une refactorisation du code devrait passer avant l'élaboration d'une API, car justement si l'API se contente de définir proprement ce l'existant, alors il suffit de glisser sur l'API et donc effacer progressivement le code actuel.

Tout ce que je veux dire ici, c'est que l'API nécessite du travail en amont pour ne pas se retrouver un code non-maintenable et avec des incohérences API/site.

Au delà de ça, je plussoie le RESTful. Rien que ça, ça suffit à définir les URLs, leurs formes, leurs paramètres :

Je ne pense pas qu'il soit nécessaire de lister les 10000 URLs du site, sachant que la thèse sur REST défini déjà des tonnes de choses qui laissent peu de marge de manoeuvre.

A fortiori, il faudra mettre en place OAuth2.

Au delà de ça, je plussoie le RESTful. Rien que ça, ça suffit à définir les URLs, leurs formes, leurs paramètres :

Comme je l'ai dit plus haut, on a besoin de savoir ce qu'on a en sorti des requetes de type GET et en entrée des requete de type PUT.

Malgré le grand nombre de +1 pour mon API de consultation, j'aime beaucoup l'idée de firm1 sur l'élaboration d'une API qui se concentre sur un workflow complet. Après, j'ai un peu peur d'une chose : les forums, c'est simple. Tout est en base de données et, techniquement, en une soirée l'API peut être développée (authentification comprise).

Par contre, des problèmes plus gros vont arrivés avec les tutoriels et les articles. Mais si, sur ce ZEP, on ne se préoccupe pas des soucis techniques, alors je suis pour le proposition de firm1.

Pour ce que tu dis Alex, si les opérations se font directement en base de données, il n'y aura aucune répétition de code. La librairie mentionnée dans le premier poste, django-rest-framework, effectue très simplement les opérations usuelles CRUD en quelques lignes par ressource. Par contre, c'est une autre affaire pour les tutoriels.

Je m'occupe de faire une révision ce soir avec tout ce qui a été dit jusqu'à présent.

Si on peut avoir un premier truc complet sur les forums rapidement, c'est tant mieux. Ok ça va prendre plus de temps de faire un truc pour les autres modules, mais au moins on aura déjà un bloc sur lequel on peut régler les problèmes lié à l'API elle même sans avoir à se soucier avec les spécificités du module. Si on arrive à un truc bon, stable et complet pour le forum, on pourra ainsi attaquer à un autre module en se concentrant justement sur ces points bloquants et pas les détails d'enrobages.

Tout est en base de données et, techniquement, en une soirée l'API peut être développée (authentification comprise). Source : Andr0

On ne doit pas avoir la même vision du taux de complexité de la chose, j'aurai plutot évalué la charge à 72h de boulot (rien qu'en developpement) sur le workflow des forums.

A l'époque, j'avais regardé la mise en oeuvre de l'API de PDP, et le tout tenait en quelques lignes. A quoi tu penses qui ferait retarder le développement de l'API de ce module précisément ?

Comme je l'ai dit plus haut, on a besoin de savoir ce qu'on a en sorti des requetes de type GET et en entrée des requete de type PUT.

En fait, si tu lis ce qu'est REST, ça utilise :

• GET : lecture des données, doit retourner une 200 avec un JSON/XML des données
• POST : création de données, doit retourner une 201, et le contenu créé en JSON/XML
• PUT : mise à jour de données, doit retourner une 204 (ou une 200 avec le contenu interprété par le serveur au besoin)
• DELETE : suppression de données, doit retourner une 204

A partir de là, sur chaque URL, on renvoi la même chose qu'à la vue classique (pour le corps, par le header, sidebar).

Typiquement si on prend le forum.

/api/v1/forums/sujet/622/zep-02-elaboration-dune-api/page/2

• GET : retourne la liste des messages de la page 2, code 200
• POST : ajoute un message, retourne le message interprété en HTML, code 201
• PUT : impossible, erreur 405
• DELETE : déplace le sujet dans la corbeille, nécessite des droits (403 sinon), code 204 si réussi

En gros, pareil qu'actuellement ça devrait être si c'est bien implémenté.

Je suis assez sensible au message d'Alex-D sur l'organisation du MVT et compagnie.

Je l'ai vécu professionnellement, je suis même encore en plein dedans, et je me pose la question à chaque projet perso que je développe.

L'approche que j'ai toujours employée est la suivante :

• on part sur un maximum de pages rendues côté serveur, avec redu conditionnel côté serveur si besoin (page HTML générée quoi)

• on passe par une phase merdique où le rendu est "templatisé" et mappé sur des données crachées en JSON par le serveur (ça, ça pue vraiment, faut limiter au max cette phase)

• on finit par du "full-API" avec effectivement un framework côté client type angularJS ou backbone

En règle générale la transition se fait assez doucement. Si le code côté serveur est bien organisé (et c'est ce qu'a l'air de dire Andr0), ça se passe sans perte ni fracas. La couche d'accès aux données est isolée, un manager "businness" contient une bonne partie de la logique client, et soit un contrôleur web, soit une méthode API REST fait appel à ce manager. La quantité de code dupliquée côté serveur est très faible.

Côté client : c'est du "tout neuf" au moment où l'on décide de se brancher sur une API. C'est certes frustrant de jeter aux orties les tags côté serveur (if / else) et d'aller coller ça dans des templates angular (ng-if, …) mais on ne duplique pas, on évolue. Rien de plus normal.

L'énorme avantage dans une plateforme open source, c'est que le mec qui développe une application mobile avec un framework web (cordova, phonegap), dispose d'une bibliothèque de template déjà écrite. Et ça, ça fait gagner un temps monumental pour les développeurs tiers (third-party).

Ensuite pour ton exemple d'URL je suis pas DU TOUT d'accord :\

ton "/page/2" n'a rien à faire selon moi dans une URL d'API de ce type. Il n'y a selon moin aucune raison que la pagination soit la même dans l'API que dans le web. Si j'ai envie de développer une timeline à la Twitter pour lire un sujet du forum, ta pagination va plus être une épine qu'autre chose. Un queryParam qui donne le nombre max d'éléments d'une page voulu (dans la limite du raisonnable pour le serveur, HTTP 400 sinon) me semble beaucoup plus adapté

Si le code côté serveur est bien organisé (et c'est ce qu'a l'air de dire Andr0)

Oulà non, je n'ai jamais dis ça !

Bah l'API de PDP a quelques failles (pas envie de les citer en public) et est loin de ce qu'on voudrait obtenir ici AMHA. Et la gestion de la sécurité avec l'authentification est un plus complexe qu'elle en a l'air.

En fait, si tu lis ce qu'est REST, ça utilise :
[…]
A partir de là, sur chaque URL, on renvoi la même chose qu'à la vue classique (pour le corps, par le header, sidebar). Source : Alex-D

Hmm, là ce ne sont que des considérations techniques, parlons plutôt métier.

Je veux créer connaitre la liste des topics crées par le membre "firm1", j'y accède par quelle url ?

• /api/v1/forums/sujets/membre/firm1/ ?
• /api/v1/forums/sujets/?membre=firm1 ?
• /api/v1/membres/firm1/sujets/ ?

Bref, écrire un ensemble d'urls cohérents. Il ne faut pas faire pareil qu'actuellement justement car il faut en profiter pour bosser cette issue des URL a travailler.

Ok, tu as sûrement plus d'expertise dans le domaine que moi, tu te rends sans doute plus compte de ce qu'il en retourne.

Je veux créer connaitre la liste des topics crées par le membre "firm1", j'y accède par quelle url ?

Pour moi, - /api/v1/forums/sujets/ : Renvoie la liste de tous les sujets de tous les forums (hell !!) ; - /api/v1/forums/sujets/?membre=firm1 : Renvoie la liste de tous les sujets de tous les forums de l'utilisateur firm1.