ZEP-17 : Elaboration de l'API des membres

Bravo ! Ça me donne envie de faire une lib ZDS en .NET tout ça …

oui ça arrivera tôt ou tard car j'ai un projet de faire une application universelle pour améliorer l'expérience utilisateur dans la lecture et l'écriture de tutoriel !

Ne vous emballez pas trop, il s'agit que de l'API des membres et c'était le module le plus simple de toute la plateforme.

Mais je suis content que le résultat final plaît. Si j'ai le temps ce soir après le Zest'Meeting, je ferais les corrections de bugs puis nous pourrons parlons d'un potentiel merge (je ne ferais le rebase qu'une fois parce qu'il risque d'être très costaud).

Oui, mais le temps qu'un second module, soit développé, on peut faire une première version de l'API .NET qui permet uniquement de gérer les membres. Et quand d'autres modules sont prêts, on les ajoute.

En tout cas j'ai hâte de pouvoir tester ça …

Bat', contacte moi par MP qu'on puisse commencer à voir ce qu'on va faire, ça sert à rien qu'on se tire dans les pattes, perso j'ai aussi ce projet et je n'ai pas envie de décourager les membres de la communauté.

Salut, Je suis impressionné par cette api. Je dis juste bravo

Bien le bonjour à tous,

Je viens solliciter votre avis sur une question que nous nous posons quant à la documentation de l'API. La documentation regrouperait toutes les possibilités de l'API et se rapprocherait plus ou moins (en plus complet), de ce qui a été résumé sur ce message. Nous avons identifié plusieurs possibilités :

• Dans la documentation back
• Dans la documentation front
• Dans le wiki du dépôt
• Sur une page du site Zeste de Savoir

Nous avions fait un premier choix en fonction de certains critères : rendre accessible la documentation de l'API au plus de monde possible et le plus visuel possible. C'est pourquoi, on s'était arrêté sur un nouveau lien, API, dans le footer du site (au même titre que CGU, A propos, L'association, Adhérer et Contact) qui redirigerait vers une URL venant de la documentation front.

Problème ? La documentation front semble voué à disparaitre et cette solution n'est donc plus envisageable.

J'aimerais donc avoir votre avis pour savoir quel est l'endroit le mieux placé pour cette documentation.

Question : est ce que cette doc d'API ne peut pas être plus ou moins automatiquement généré ?

La doc back à un gros avantage, elle est lié au code et même si ce n'est actuellement pas utilisé, il y a une raison si Sphinx a été utilisé : on peut la généré en partie automatiquement grace aux doc-string.

Si les outils lié a la mise en place de l'API permettent de faire générer une doc quasi automatiquement, je suis pour qu'on ne se prenne pas la tête et qu'on l'utilise. Il y a plus de chance qu'elle soit mise a jour si c'est fait automatiquement que si on doit le faire manuellement.

Perso plusieurs docs à des endroits différents ne me gène pas quand ça se justifie.

Il existe effectivement des outils permettant de générer une doc api automatiquement. J'utilise par exemple Swagger au boulot pour l'instant et ça marche plutôt pas mal quand on veut ne pas devoir maintenir à la main.

Problème

Il existe bien ceci : https://github.com/marcgibbons/django-rest-swagger . Malheureusement, il semble que cela ne soit pas compatible avec django-rest-framework v3+.

Du coup, j'ai abandonné cette solution.

Si quelqu'un connait un outil du même genre facile à mettre en place, c'est évidemment avec plaisir qu'on tentera de l'utiliser, mais donc pour l'instant on est plutôt parti sur une doc écrite à la main, effectivement.

Voici toutes les solutions "officielles" possibles pour générer la documentation de l'API.

Ah oui, j'étais tombée sur cette page aussi en regardant pour Swagger. Je peux toujours tenter de mettre en place une des autres solutions pour voir ce que ça donne.

Apiary a l'air pas mal complet. Je jetterai un oeil cette semaine sur tout ça. Si quelqu'un d'autre veut tenter aussi, ou a un retour à faire sur un de ces outils, qu'il n'hésite pas !

J'essayerais un peu ce soir aussi mais je ne compte pas y perdre des cheveux.

L'avis de Gustavi :

Pour moi, cétait évident que ça serait intégré dans la doc actuelle mais je peux me tromper.

Faut bien se dire qu'avoir plusieurs doc c'est la merde. J'en ai fait les frais lorsque j'ai voulu faire un fork (j'ai du chercher des infos à 4 enroits différents (ReadTheDoc, GitHub, doc front et preprod) et j'ai pété un cable).

(tu peux ajouter ce point de vue à ton message sur la ZEP)

Breaking news : Andr0 a réussi finalement à intégrer Swagger, on aura donc une doc générée automatiquement. \o/

Grâce au super boulot d'Andr0 ces derniers jours, vous pouvez vous attendre à une super PR de la mort qui tue bientôt. Prêts à QA ?

Pour ceux qui se sentent l'âme d'un testeur, nous avons besoin de QA pour la PR de la ZEP.

Pas grand chose à dire d'autre que : MERCI à tous les participants de cette ZEP !

Félicitations.

J'ai pas envie d'être chiant, mais faudrait pas plutôt faire une QA auto pour ça ? N'importe quel langage permet de faire des requêtes API, parser du JSON, envoyer des headers débiles etc. Et c'est beaucoup beaucoup plus pérenne de tester de la sorte plutôt que de refaire de la QA :\

Genre créer son compte, se connecter etc. Tout ça devrait avoir sa place dans un client écrit dans le langage que vous voulez et bingo, à chaque modif sur l'API on se fade tous les tests auto d'API.

Désolé d'être rabat-joie vraiment, vous avez abattu un travail énorme et y'a vraiment de quoi se réjouir, mais c'est dommage de recetter ça à la main.

Tiens j'ai d'autres questions point de vu utilisateur : comment on récupère les infos "client" si on veut accéder à des routes qui nécessitent une authentification ?

Javier : Rien n'empêche les gens qui vont QA la PR de faire des tests automatiques comme tu le décris. L'idée c'est de tester le plus possible pour y trouver tous les bugs possibles.

Kje : Je comprends mal ta question. Est-ce que tu pourrais la formuler autrement ?

Si je comprend bien ta description de l'api, certaines actions nécessitent, et c'est normal, une authentification. Or pour s’identifier il faut fournir certaines informations, dont les client_id et client_secret. Comment ce passe la procédure pour les récupérer ? Est ce que ça doit etre fait manuellement par un admin ou une interface est prévu pour les demander.

Au passage dans les exemples que tu donne, quand on demande l'info sur un membre, il semble qu'on récupère son adresse mail. Est ce vraiment une bonne idée si cette API est publique de fournir le mail à tout le monde ?

Si je comprend bien ta description de l'api, certaines actions nécessitent, et c'est normal, une authentification. Or pour s’identifier il faut fournir certaines informations, dont les client_id et client_secret. Comment ce passe la procédure pour les récupérer ? Est ce que ça doit etre fait manuellement par un admin ou une interface est prévu pour les demander.

Je comprends mieux. Pour le moment, il faut passer par l'interface administrateur pour lui demander de créer un client et récupérer ces informations clientes. Cette ZEP était l'occasion d'intégrer beaucoup de choses hors scope (et plutôt dans le scope de la ZEP mère, la ZEP-02) mais cette fonctionnalité précise était plutôt un confort d'utilisation qu'un obstacle technique. Nous laissons donc le soin aux développeurs habituels de la plateforme de proposer une interface développeur simple pour récupérer ces informations sans l'intervention d'un administrateur.

Au passage dans les exemples que tu donne, quand on demande l'info sur un membre, il semble qu'on récupère son adresse mail. Est ce vraiment une bonne idée si cette API est publique de fournir le mail à tout le monde ?

Je suis en train de mettre à jour le message. En fait, l'e-mail est uniquement renvoyé si le membre accepte de divulger son adresse e-mail. Dans le cas contraire, il ne sera jamais affiché.