ZEP-17 : Elaboration de l'API des membres

"Est-ce-qu'un membre du staff a accès à plus de fonctions sur l'API qu'un simple membre authentifié"

Je pense que Oui. Les staff sont des membres tres actifs du site, par définition, et ils sont souvent les premiers a mettre en place des outils externe pour le site.

Par exemple sur le sdz presque TOUS les staff utilisaient une extension de navigateur pour faciliter leur travail. Donc je pense que leur support explicite est important et utile.

"Est-ce-que certaines fonctions (primitives) de l'API sont différentes en fonction de la nature de la personne authentifiée"

Je ne vois pas. Un staff a juste le droit de faire certaines actions en plus. A noter tout de meme que certaines primitives peuvent renvoyer plus d'infos. Par exemple pour un membre, les staff ont quelques infos en plus que les simples membres.

est-ce-qu'en tant que staff, il se peut que je veuille exécuter des actions ou consulter des données en tant que simple membre ?

Je ne vois pas de raisons de le faire et ce n'est pas possible avec le site donc bon…

Après mon avis est peut être biaisé parce que je vois l'API mais aussi l'utilisation potentielle qu'on pourrait en faire ailleurs que sur zestedesavoir.com.

Mais le seul truc qui m'embête c'est le même que là ou a tilté Andr0. Aujourd'hui le staff n'est qu'un groupe qui a des permissions particulières (au niveau django) et un forum particulier. On a un groupe "dev" aussi, mais sans permissions en plus. Mais si demain on décide de donner des permissions (ou même un nouveau forum) au groupe "dev", il faudra revoir l'api pour rajouter un autre path spécial devs. Idem pour n'importe quel groupe qu'on pourrait rajouter, l'API ne suivra pas automatiquement.

firm1, c'est pas exactement ce sur quoi j'ai tilté. Je vais illustrer ce que je voulais dire :

• Les visiteurs peuvent consulter la fiche d'un membre : Aucun problème.
• Les utilisateurs peuvent consulter et modifier leur mot de passe : Aucun problème.
• Le staff peut consulter et modifier le mot de passe et le pseudo d'un membre.

Nous aurons donc quoi concrètement (si je comprends bien) ?

• GET api.zestedesavoir.com/v0.5/public/membres/1 : Consultation
• PUT api.zestedesavoir.com/v0.5/user/membres/1 : Modification uniquement du mot de passe
• PUT api.zestedesavoir.com/v0.5/staff/membres/1 : Modification du mot de passe et du pseudo

On risque donc d'avoir de la répétition de code par exemple.

Si vous vous débrouillez bien y'aura pas de répétition de code je pense, ça reste juste un mapping.

M'étonnerait qu'avec Django et les dev que vous avez vous n'ayez pas un "manager" d'assez haut niveau qui s'occupe de fournir les bonnes données en fonction du contexte.

Que le contexte soit déterminé en fonction du path de l'API ou du token utilisé, j'imagine que dans les deux cas c'est injecté automatiquement non ? (décorateur, ou autres). firm1 arrête moi si je me trompe.

La question est plus fonctionnelle en fait.

Si vous ne voyez aucun intérêt à saucissonner l'API en différents paths pour différents rôles (qui ne sont pas nécessairement les mêmes rôles que sur le site d'ailleurs) type public, authenticated, superuser c'est certainement qu'à l'heure où on écrit ces lignes il n'y en a pas.

Dans ce cas faut pas chercher midi à 14h, restez sur un contexte injecté automatiquement en fonction du token présent dans les credentials. Ça fonctionnera très bien.

Est-ce-que ça sera pérenne ? Bah là c'est une bagarre de petits doigts avec firm1 mais on va pas bloquer la ZEP pour ça.

Du coup, je me demande si cette question ne pourra pas se résoudre par elle même pendant le développement. Mentionnez les deux dans une nouvelle révision du premier message de cette ZEP et adoptez la solution la plus adaptée lorsque le développeur sera confronté à ce choix.

Ca vous va ?

Moi je suis plutot pour. Dans tous les cas des problèmes ou questions vont apparaître pendant le dev, il faudra ajuster la spec en fonction. Donc ce point peut en faire partie.

ça me va perso.

Il y'a encore à résoudre cette question

Tu parles de ca ?

il y'a la biographie, ainsi que la signature qui ne peuvent pas être interprété decemment si on donne du markdown. Donc pour moi, il faut en discutter quelque part pour pouvoir valider cette ZEP.

Pas sur qu'il y ait une seule bonne reponse… Si on renvoi le markdown, alors le client doit savoir l’interpréter (avec nos specs). Si on renvoi le format html, alors idem mais c'est plus standard.

Je pense qu'on était tous d'accord pour dire qu'il fallait laisser le choix au client. Notamment si un client souhaite utiliser son propre parser markdown pour X raison (format d'affichage chez lui, …) avec un fallback sur du HTML si le client n'a rien spécifié.

Les questions soulevées selon moi :

1. Demander au client d'envoyer le Content-Type souhaité, dans un header (custom, le "Accept" est utilisé ailleurs) à définir. => choix d'un nom pour ce header : X-Data-Format ou autre

• Lister les Content-Type acceptés et qu'on sait renvoyer : text/html, text/markdown, text/plain ? On aurait une version plein texte d'un texte au format MD (avec liens entre parenthèses par exemple, et que sais-je encore) ? Est-ce-que j'en oublie ?

C'est là-dessus qu'il faut faire le point. firm1 voulait faire un petit tour de l'état de l'art pour savoir quel nom employer pour le header (et même savoir si un header était la bonne façon de faire). J'ai pas vraiment trouvé de truc semblable pour ma part.

On aurait une version plein texte d'un texte au format MD (avec liens entre parenthèses par exemple, et que sais-je encore)

C'est possible à faire mais actuellement non disponible. Par contre doit bien y avoir des trucs bateaux qui peuvent le faire directement depuis le html.

Je crois que Javier a bien résumé le point. M'enfin, de ce que j'ai pu voir de mes recherches, la meilleure solution reste une info dans le header style X-Quelque-chose. Donc je suis bien d'accord avec Javier pour utiliser le X-Data-Format.

Pour les format de données que l'ont sait renvoyer, on a le html et le markdown. On sait aussi renvoyer le text via la fonction striptags de django. Donc pour les trois formats ci-dessous je dis ok.

Après avoir validé ça, je ne vois plus rien qui puisse bloquer la ZEP (en tout cas pour moi).

Effectivement, ce que dit Javier me semblait acté mais c'est ma faute, je n'avais pas mis à jour le premier message de la ZEP.

Pour résumé :

• Il existe 2 solutions envisageables pour la gestion des rôles/droits d'accès aux ressources. Ce problème sera traité le moment venu par le développeur en fonction de ce qui lui semblera le plus naturel dans la mise en oeuvre actuel du back.

• Les ressources Markdown sont renvoyées dans le corps de la requête HTTP et suivant le format indiqué dans le header de la requête avec la clé X-Data-Format. Les formats supportés seront markdown, html et texte.

Voilà, je serais plus complet quand je ferais la révision mais sommes-nous d'accord pour ces deux derniers points ? Si oui, pouvons-nous passer cette ZEP en validation ?

:')

Go !

\o/

Bien, j'ai mis à jour le premier message de la ZEP qui passe en révision 4 et en validation. Si quelqu'un à envie de relire pour faire les dernières remarques, qu'il le fasse maintenant (ou se taise à jamais … lulz).

Je passerais la ZEP au statut "Accepté" très prochainement si personne n'a de remarques.

Après avoir lu en diagonale le sujet, j'aimerais demander quelque chose:

Dans l'objectif d'un usage interne (c-à-d sur le site même, pas via un client tiers), est-ce que la recherche de membre peut passer avant tout le process d'authentification, et la modification de membre ?

Je n'ai aucune idée de si c'est plus long à dev, mais pour moi c'est utile pour une utilisation sur le site (contrairement au reste, qui sera utile au site mais bien plus tard ), c'est pour l'autocomplétion des pseudos (autant dans les MPs, que dans les futures @mentions). Actuellement, de mémoire, pour les pseudos, on fait une requète sur /membres/?q={query} avec le header Accept: application/json pour récupérer un array JSON avec id et pseudo. Si l'on pouvait avoir plus de choses, type avatar, statut (staff ou non), "url" du membre… ça permettrait d'améliorer cette autocomplétion

C'est pas non plus archi-prioritaire, mais si l'autocomplétion peut être le premier module interne à utiliser l'API, pourquoi pas

J'aimerais ajouter quelque chose pour l'authentification: Est-ce que l'auth. OAuth2 est nécessaire depuis le site ? Je veux dire, si l'on doit gérer access token, etc. , alors que de toutes façons on envoie les cookies avec la session, et donc les informations sur l'utilisateur loggé, je pense qu'il vaut mieux ne pas demander de token si l'on fait la requête depuis le site (si c'était déjà l'idée, ça serait bien de préciser ça dans le premier post )

Sinon, la réponse JSON me parait pas mal, si l'on pouvait juste permettre de "filtrer" les champs à donner. Par exemple, pour reprendre l'autocomplétion, je n'ai pas besoin de la biographie, ou encore de la signature. J'aimerais, en tant que dev, pouvoir demander "juste" l'id, le pseudo, et l'avatar quand fait une recherche dans les membres

En tout cas, j'ai hâte que cette API voie le jour

Sandhose

EDIT: Je viens de voir la partie sur le process d'authentification.

Pour moi, l'authentification dans une appli tierce se fait de cette manière: (c'est d'ailleurs le cas dans la plusieurs services qui offrent une API, genre Google ou Twitter)

• Le développer demande ses clés d'API
• L'appli demande l'accès à l'API pour l'utilisateur
• L'appli ouvre une popup (ou une vue web pour une appli native) avec soit
• Le formulaire avec login / mot de passe, si l'utilisateur n'était pas loggé sur le site avant
• La demande d'autorisation, avec une image de l'appli, et les différentes permissions demandées (en supposant qu'on ai un jour un moyen de "limiter" l'API à certains scopes)
• Après le login/la confirmation de l'utilisateur, le site redirige vers l'URL que le développeur a spécifié auparavant (l'URL de callback OAuth), avec en paramètre GET un code d'autorisation
• L'application échange ce code contre l'acces token, et le refresh token

C'est en gros le même flow que pour les API google

Dans l'objectif d'un usage interne (c-à-d sur le site même, pas via un client tiers), est-ce que la recherche de membre peut passer avant tout le process d'authentification, et la modification de membre ?

Clairement, non. Pour pouvoir effectuer des requêtes plus complexes sur une API, il faut d'abord qu'elle fonctionne correctement et que les bases soient seines (ce qui n'est pour l'instant pas le cas). C'est pourquoi ça sera fait à la fois, voire hors scope à cette ZEP.

Alors oui, c'est peut-être utile pour toi mais toutes les fonctionnalités d'une API sont potentiellement utile. Récupérer un membre en particulier, la liste des membres ou la possibilité de les modifier sont des uses cases tout aussi importants. Il n'y a pas de fonctionnalités prioritaires sur les autres ci ce n'est l'ordre que nous avons définis tout au long de la rédaction de cette ZEP.

Puis, une mise en oeuvre direct dans le projet Zeste de Savoir ne me semble pas être une bonne idée.

J'aimerais ajouter quelque chose pour l'authentification: Est-ce que l'auth. OAuth2 est nécessaire depuis le site ?

L'authentification depuis le site n'a rien à voir avec l'authentification via l'API. Ce sont deux choses différents sans aucun lien (dans le process).

Sinon, la réponse JSON me parait pas mal, si l'on pouvait juste permettre de "filtrer" les champs à donner.

Personnellement, je n'ai jamais vu ça dans une API et, si nous le proposons, je pense que ça doit être une décision réfléchie plus en profondeur. Comme pour le premier point, attendons d'avoir une API stable avant de commencer à vouloir faire des choses plus poussées. Ne mettons pas la charrue avant les boeufs.

Pour moi, l'authentification dans une appli tierce se fait de cette manière: (c'est d'ailleurs le cas dans la plusieurs services qui offrent une API, genre Google ou Twitter)

Tu parles de mise en oeuvre du système d'authentification. De 1, notre système permettra ton process sans le moindre souci. De 2, nous ne réfléchissons pas aux potentielles misent en oeuvre ici mais au protocole bas niveau.

100% d'accord.

100% d'accord.

100% d'accord

ça fait bizarre d'être 100% d'accord avec Andr0

@firm1 : Qui es-tu et qu'est ce que tu as fais du vrai firm1 ?!

Non mais tu as aussi aidé à rédiger cette ZEP. Je suppose que c'est normal que nous ayons plus ou moins le même avis et la même vision des choses sur l'API.

Je suis d'accord avec vous mais Sandhose soulève un point intéressant que j'avais relevé ici. i.e. le cas où une application n'effectue pas une requête EN TANT qu'un utilisateur, mais plutôt en tant… … qu'elle même… Et j'avais pensé à des lecteurs d'activité, des trucs un peu marginaux mais j'avais omis le site lui-même, c'est la même problématique.

Dans le cas que tu décris Sandhose, tu n'aurais pas besoin de token. Tu tapes sur la partie publique de l'API.

A partir du moment où le site va lui-même taper sur l'API (avec l'utilisateur loggé) ce que je fais en général c'est que je crée à un processus de login "court-circuité" (pas de callback à la OAuth, etc.).

Ça m'a toujours paru logique de traiter exactement de la même façon (primitives, …) une API utilisée en externe et une API utilisée en interne à l'exception du login.

Mais encore une fois c'est mon choix, pas sûr que ça fasse l'unanimité.