ZEP-17 : Elaboration de l'API des membres

Comme je l'ai déjà dis, bravo pour cette PR.

Maintenant, je pense aussi comme Javier, la PR devrait être auto testable parce que c'est possible de tester ça automatiquement et ça fera gagner énormément de temps pour la suite. Car là ça voudrait dire qu'a chaque nouvelle PR il faudra retester toute l'API à la main pour vérifier qu'on a pas de régression.

La ZEP n'est pas urgentissime, donc vaudrait mieux prendre le temps de faire les choses bien.

Très bien, est-ce que vous avez des solutions pour tester automatiquement cette ZEP ? Sachez toutefois que j'ai rajouté 63 tests pour l'API dans la soirée.

Autre chose, j'aimerais avoir votre avis sur une question : Pour l'instant, la documentation générée par l'API sera accessible dans le footer d'une instance de la plateforme Zeste de Savoir. Est-ce que vous pensez qu'elle doit aussi être accessible dans la documentation du projet GitHub ? Si oui, où ça ? Si non, pourquoi ?

En tout cas, merci beaucoup pour les remerciements. Sachez que c'est avant tout un travail d'équipe. Gustavi, Taguan et même Situphen sont aussi méritants que moi !

Est-ce que vous pensez qu'elle doit aussi être accessible dans la documentation du projet GitHub ? Si oui, où ça ? Si non, pourquoi ?

On peut effectivement la citer oui, dans le readme ou dans la doc Sphinx… De toute façon faut rationaliser ça…

Mon avis sur la question était que la documentation de l'API n'est pas destinée aux développeurs de la plateforme (ou indirectement) mais plutôt aux développeurs tiers. Cela me semblait donc logique de rajouter un lien dans le footer qui pourrait devenir, plus tard, un portail pour les développeurs autour de Zeste de Savoir.

J'avais fais exprès de l'omettre dans la documentation du projet de Zeste de Savoir mais, suite à la PR sur le dépôt officiel, j'ai eu des retours comme quoi il serait nécessaire de rajouter cette information dans la documentation. J'y ai réfléchi et ma conclusion est : Pourquoi pas, mais pas sous la même forme. Dans la documentation du projet, il faut signaler comment fonctionne la génération de cette documentation, comment elle peut être maintenue et comment y accéder.

Je pense que nous serons d'accord là dessus. Du moins, je l'espère.

J'aime bien cette idée de mettre la doc "utilisation de l'API" accessible au public (dans le footer ça me paraît bien) et la doc "fonctionnement interne de l'API" dans les docs techniques.

Je comprend la nuance Andr0 mais en tant que Dev, si je tombe sur un projet OpenSource, j'aurais tendance à aller chercher la doc API avec celle du reste de la plateforme.

En soit je ne pense pas que ce soit genant qu'il soit présent sur les deux, en spécifiant bien qu'il s'agit de la doc spécifique à cette instance.

Typiquement imaginons le besoin suivant :

• La plateforme zds est en v42
• L'api quant à elle est en v20
• Moi j'ai commencé à développer une application mobile en me basant sur la v10 de l'api
• Vu que la doc de l'API n'est dispo qu'au travers de la plateforme, je n'ai accès qu'a la doc de l'API en v20 (avec donc plein de choses qui ne me concernent pas).

Ma question : comment j'accède a la doc de la version qui m’intéresse ?

Réponse naïve : si la doc était sur Sphinx, je n'aurai qu'a aller la lire en ligne la version correspondant au bon tag.

Kje : Pour moi, peu importe que le projet soit open-source ou non. Personnellement, si je veux accéder à une API, j'aurais plutôt tendance à aller sur le site plutôt que sur la documentation où il va y avoir plein de choses qui ne m'intéressent pas du tout. Cela, la finalité est la même de mon message et du tiens. Dans le fond, nous sommes d'accord je pense.

firm1 : L'API n'est pas versionnée.

Je ne comprend pas.

Dans la mise en oeuvre actuelle, il n'y a aucun versionning. Rien n'est prévu dans la bibliothèque DRF pour versionner une API. C'est ma faute, j'ai oublié de le spécifier dans le message récapitulatif. Je modifie ça.

Donc si je comprend bien, un client de l'API ne pourra l'utiliser que dans sa dernière version version tout le temps ? Au delà du fait que ce n'est pas très Continuous tout ça :-°, ça voudra dire qu'un développeur lambda qui utilise l'API devra rentrer dans notre processus de release et donc aura 2 semaines de preprod pour vérifier que la mise à jour de l'API ne lui casse pas une fonctionnalité.

En gros, ça ne me semble pas viable sur le moyen terme comme pratique.

Bien, le versionning arrive avec la release 3.1 de la bibliothèque DRF qui n'est pas encore sortie. Partons du principe que notre API sera versionnée.

Si nous partons de ce principe et que la documentation est générée automatiquement par Swagger, il devra supporter ce versionning et permettre de consulter toutes les versions d'une API. Je ne vois donc pas le problème.

En même temps on peut pas se permettre de gérer 50 versions en parralèle. Si l'API est correctement testé, il ne devrait pas y avoir de regression.

A titre personnel je pense que :

• Jusqu'à ce que l'API soit complète (tous les modules couverts), on ne versionne pas et on fait attention à ne pas introduire de régression (grace à des tests).
• L'admin qui va générer les clés clients peut garder trace des pseudos des membres en ayant récupérer une pour les informer si des regressions doivent être introduite. Ceci pourra être fait automatiquement si un module dédié de demande de clé est developpé, ce qui permettra aux dev d'informer des changements ceux qui ont fait une demande de clé.
• On communique sur les changements, entre autre via les articles comme on le fait déjà.
• Si ton appli est elle aussi correctement testé, tu devrais pouvoir détecter les regressions facilement sur la préprod aussi.
• Quand on aura une API complète, il sera toujours temps d'en reparler à ce moment mais actuellement les efforts suivant vont se concentrer sur augmenter la couverture de l'API plus que changer son comportement.
• On a qu'a dire que tant que l'API n'est pas complète, cette fonctionnalité est en beta avec les conséquences sur la stabilité que ça engendre. Si c'est écrit en gros, les dev externe sauront à quoi s'en tenir.

Kje : Même si je suis d'accord avec toi, j'aurais bien aimé versionner notre API pour une version bêta en fait (dès que la release sera faite). Histoire d'apprendre comment ça se passe et pour faire une API vraiment sympa.

Indeed mais si DRF ne l'introduit que dans la prochaine version, ça sert a rien de se casser la tête. L'API restera avec un statut de beta tant que tout n'est pas couvert de toute façon. Donc autant se concentrer sur une couverture maximal de la plateforme avant de gérer ça. Je ne vois pas de problème que le versionnement n'arrive que plus tard. D'autant que soyons honnête, a moyen terme les clients de l'API vont représenter au max 10 developpeurs, dev qui suivent de pret ces sujets.

Pour l'histoire du versionning, on peut partir sur le fait que l'API est en beta, ça ne me dérange pas tant que c'est présenté ainsi. Mais pour la documentation, quasi toutes les API que j'ai déjà utilisé (Bitbucket, hbase, Elasticsearch, Ambari, etc. ) open source, ont une documentation accessible en dehors de leur plateforme.

firm1 : Clairement, je ne vois pas l'utilité de maintenir une documentation à l'identique de la documentation générée automatiquement par swagger avec les erreurs possibles en plus (documentation pas à jour, erreurs humaines, etc.).

D'accord avec Andr0, je n'en vois pas l'intérêt a priori. Un lien vers cette doc depuis la doc technique oui, bien sûr, mais sinon qu'est-ce que ça change que ce soit sur le site ou ailleurs, tant que c'est versionné ?

Je suis d'accord pour le fait que "tant que c'est en beta, on part du principe que ce n'est pas versionné"

Par contre :

Si l'API est correctement testé, il ne devrait pas y avoir de regression.

Ça c'est un faux bon principe.

Crois moi, quand tu design une API t'es obligé de casser la rétrocompatibilité à un moment. Si tu ne versionnes pas t'es mort, tu peux plus avancer. Ne serait-ce que pour repartir sur des bases saines, de gérer le login de façon différente etc.

Si tu commences à vouloir être rétrocompatible partout (attention y'a une différence fondamentale entre régression et rétrocompatibilité ! ça n'a rien à voir !) tu vas te retrouver avec un plat de spaghetti infâme côté serveur avec du code "qui est là mais on sait pas trop si les clients l'utilisent, on déprécie ? bah non, on peut pas changer de version".

Faut vraiment vraiment gaffe avec ça.

PS : je serais presque partant pour indiquer à la place de là où l'on indique le numéro de version de l'API (path ou header, me souviens plus de la décision) beta à la place de 1.

+1 Javier.

Disons, que dans des projets opensource je ne sais pas vous, mais je n'ai pas l'habitude des docs d'API qui ne font que balancer des l'url (la doc étant une partie importante de l'API).

Typiquement avec un descriptif à la swagger, il faudra trouver un autre moyen pour rajouter quelque part :

• La procédure pour demander un accès client
• Comment je m'authentifie (en général on fournit des exemples avec curl)
• Quels sont les entêtes que je peux envoyer
• Les types des données et les limitations en taille (les pseudo sur ZdS ne doivent pas dépasser 30 caractères par exemple) que je peux envoyer/recevoir via cette API
• etc.

En gros, la spécification de la ZEP devrait plus ou moins rentrer dans la documentation.

@Javier : Oui mais si je parle des tests c'est autant et surtout pour detecter les regression. Tu remarquera que dans le suite je propose qu'on informe les dev quand il y aura des choses de cassés. Je suis loin d'etre contre casser la rétro compatibilité. Je dis juste que c'est pas l'urgence de l'assurer, d'autant que ce sera supporté presque automatiquement dans quelques mois.

Bref pour moi, on continue en indiquant un gros "beta" sur ce service et quand DRF supportera le verisonnement, on pourra en reparler et sortir de la beta avec un versionnement.