Oui donc on revient a la proposition de Javier. Je proposais juste que par defaut on est une version intermediaire avec juste les infos importantes (id, pseudo et avatar) et qu'on puisse avoir la version minimal ou complete avec un paramètre. Mais en soit je m'en fout un peu.
J'insiste sur le fait qu'il faudrait, en plus de l'identifiant, un lien vers la ressource complète dans le cas où expand=false.
Tout comme Taguan, je pense que c'est une bonne pratique.
Oui donc on revient a la proposition de Javier. Je proposais juste que par defaut on est une version intermediaire avec juste les infos importantes (id, pseudo et avatar) et qu'on puisse avoir la version minimal ou complete avec un paramètre. Mais en soit je m'en fout un peu.
Si je comprends bien, tu proposes que si nous spécifions rien, nous renvoyons l'identifiant, le pseudo et l'url de l'avatar au lieu de simplement les identifiants mais de permettre d'étendre certains attributs avec le query expand ?
J'insiste sur le fait qu'il faudrait, en plus de l'identifiant, un lien vers la ressource complète dans le cas où
expand=false.
Je ne suis pas sûr de bien comprendre. Un exemple ?
Cf. le lien stackoverflow que j'ai donné sur la page précédente.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | { "pk": 654321, "title": "Titre du MP", "subtitle": "Sous-titre du MP", "pubdate": "1977-04-22T06:00:00Z", "author": { "id": 42, "self": "http://api.zestedesavoir.com/membres/42", }, "participants": [ { "id": 42, "self": "http://api.zestedesavoir.com/membres/42", }, { "id": 5, "self": "http://api.zestedesavoir.com/membres/5", } ], "last_message": 123456 } |
Après, on peut choisir un autre mot-clef que self, resource_url, resource_uri, …
Si je comprends bien, tu proposes que si nous spécifions rien, nous renvoyons l'identifiant, le pseudo et l'url de l'avatar au lieu de simplement les identifiants mais de permettre d'étendre certains attributs avec le query expand ?
En gros oui. Sachant que dans l'idéal il y aurait aussi un parametre pour ne récupérer que la version "id seulement" pour les rares applications où il n'y a que ça de necessaire.
Ok, je pense avoir bien compris toutes vos idées. Je vous fais une proposition ce soir à ce sujet pour une nouvelle révision.
Je vous propose une nouvelle révision en espérant avoir compris toutes vos remarques.
| Cartouche | |
|---|---|
| ZEP | 23 |
| Titre | Elaboration de l'API des MPs |
| Révision | 3 |
| Date de création | 15 Janvier 2015 |
| Dernière révision | 6 Février 2015 |
| Type | Feature |
| Statut | Rédaction |
Cette ZEP ci-présente est une ZEP fille de la ZEP-02 qui concerne l'élaboration d'une API au sens large, c'est-à-dire qu'elle traite toutes les questions générales comme l'authentification, les codes HTTPs, les erreurs, la sécurité, etc.
Suite à la ZEP 17 sur l'élaboration d'une API pour les membres, cette ZEP 23 voit le jour pour la rédaction de l'API des MPs.
Permettre aux clients de récupérer, ajouter, modifier ou supprimer les MPs d'un membre donné et d'effectuer une première association entre deux modules puisque des MPs sont détenus par des membres.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "pk": 654321, "title": "Titre du MP", "subtitle": "Sous-titre du MP", "pubdate": "1977-04-22T06:00:00Z", "author": { "pk": 42, "username": "Clem", "self": "http://api.zestedesavoir.com/membres/42" }, "participants": [ { "pk": 42, "username": "Clem", "self": "http://api.zestedesavoir.com/membres/42" }, { "pk": 5, "username": "Andr0", "self": "http://api.zestedesavoir.com/membres/5" } ], "last_message": 123456, } |
| Colonne | Type | Description |
|---|---|---|
| pk | long | Identifiant du sujet |
| title | String | Titre du MP |
| subtitle | String | Sous-titre du MP |
| pubdate | Date | Date de publication du MP |
| author | User | Auteur du MP |
| participants | Array User | Liste des participants du MP |
| last_message | Message | Dernier message du MP |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "pk": 123456, "privatetopic": 654321, "text": "# Contenu du message", # En fonction du paramètre X-Data-Format "text_html": "<h1>Contenu du message</h1>", # En fonction du paramètre X-Data-Format "pubdate": "1977-04-22T06:00:00Z", "update": "1977-04-22T06:00:00Z", "position_in_topic": 1, "author": { "pk": 42, "username": "Clem", "self": "http://api.zestedesavoir.com/membres/42" } } |
| Colonne | Type | Description |
|---|---|---|
| pk | long | Identifiant du message |
| privatetopic | long | Identifiant du sujet |
| text | String | Contenu du message en Markdown |
| text_html | String | Contenu du message en HTML |
| pubdate | Date | Date de publication du message |
| update | Date | Date de dernière édition du message |
| position_in_topic | entier | Position du message dans le sujet |
Par défaut, les objets d'une autre ressource contenus dans une réponse (dans ce cas présent, les objets sur les membres avec participants et author) renvoient le minimum d'information, à savoir l'identifiant, le pseudonyme et l'URL de la ressource correspondante.
Cependant, il sera possible de renseigner une query expand pour récupérer toutes les informations de l'attribut donné. Par exemple, si expand prend la valeur author, toutes les informations concernant l'auteur seront renvoyées.
Fonctionnalité : Renvoie une liste paginée pour lister les MPs d'un membre connecté par 10.
URL : http://api.zestedesavoir.com/mps/
Méthode : GET
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Renvoie les informations concernant un MP donné. Le message est alors considéré comme lu par le système pour l'utilisateur qui fait la requête.
URL : http://api.zestedesavoir.com/mps/{id}
Méthode : GET
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Création d'un nouveau MP avec plusieurs participants
URL : http://api.zestedesavoir.com/mps/
Méthode : POST
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Ajoute un ou plusieurs participants dans un MP donné.
URL : http://api.zestedesavoir.com/mps/{id}/
Méthode : PUT
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Se retirer d'une liste de conversations.
URL : http://api.zestedesavoir.com/mps/
Méthode : DELETE
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Se retirer d'une conversation.
URL : http://api.zestedesavoir.com/mps/{id}/
Méthode : DELETE
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Renvoie une liste paginée pour lister les messages d'un MP par 10.
URL : http://api.zestedesavoir.com/mps/{id}/messages/
Méthode : GET
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Renvoie les informations concernant un MP donné.
URL : http://api.zestedesavoir.com/mps/{id}/messages/{id-mes}/
Méthode : GET
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Ajoute un message dans un MP de l'utilisateur.
URL : http://api.zestedesavoir.com/mps/{id}/messages/
Méthode : POST
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Fonctionnalité : Editer le dernier message d'un MP si c'est celui de l'utilisateur.
URL : http://api.zestedesavoir.com/mps/{id}/messages/{id-mes}/
Méthode : PUT
Headers :
Paramètres :
Codes HTTP :
Permissions nécessaires :
Bien, je suppose que la révision convient à tout le monde. Puisque l'API des membres est maintenant mergé et prévu pour la release 1.6, je vous propose de passer cette ZEP en validation pour l'accepter ou non par les membres du staff.
je vous propose de passer cette ZEP en validation pour l'accepter ou non par les membres
du staff.
Fix'd.
BTW, ok pour pour moi
La validation
Lorsque la proposition est arrivée à un état stable et mature, elle prend le statut Validation. Le Staff et/ou les développeurs principaux du site (et/ou le conseil d'administration de l'association si son implication est nécessaire), faisant autorité pour valider la ZEP, se chargent alors de la relire pour l'accepter ou non.
[HS] Ok, c'est là bas que je vais critiquer alors. Pour moi ça ne doit être le staff que quand c'est un processus qui les concerne (validation, etc.). Dans le cas d'une API je pense que la partie " les développeurs principaux du site" est la plus importante.
(dans un cas comme dans l'autre je ne suis pas concerné du coup) [/HS]
Bien après une journée, personne ne semble contre l'idée de basculer cette ZEP en validation. Je le fais donc dès maintenant !
Bon, je pense que nous allons passer la ZEP en développement devant l'absence d'intervention des développeurs et du staff. D'ailleurs, j'ai déjà déblayé le terrain avec le refacto du module des MPs.
Salut tout le monde,
Je viens donner des nouvelles au sujet de cette ZEP et vous informez que je compte bien la développer. J'avoue que j'en avais un peu marre de l'API, j'ai fais une petite pause pour développer le SDK Android (d'ailleurs, j'arrive à faire mes premières requêtes HTTP vers l'API avec tout le mécanisme de cache et de persistances des données derrière, c'est vraiment top mais c'est pas l'objet de ce message. 
C'est donc pour vous signalez que j'ai décidé de m'y remettre doucement et grâce à la fin de soirée d'hier et d'aujourd'hui, il est dorénavent possible de récupérer la liste de ses propres messages privées et d'en afficher les détails. La documentation et les tests sont compris dans ces nouvelles fonctionnalités.
Cela commence en douceur, je n'aurais pas le temps de développer ce week-end mais j'ai dégagé du temps pour y passer mes soirées de la semaine prochaine. Vu la rapidité à laquelle j'ai développé les deux premières vues, je pense qu'il pourrait en être de même pour les autres vues (du moins, pour une bonne partie).
Voilà, c'était pour vous tenir au courant ! 
Tu nous fais rêver Andro !
Ca fait un moment que je ne suis pas venu poster ici et pour cause, il y a eu des choses bien plus urgentes (release 1.8 avec Django 1.7, les problèmes du serveur) et une énorme flemme de ma part puisque j'étais plus ou moins bloqué sur des problèmes techniques, ou du moins je ne trouvais pas mes solutions propres et satisfaisantes. C'est donc sans grand conviction que je me suis posé sur mon ordinateur ce matin (enfin hier matin).
Puis j'ai codé et j'ai débloqué une bonne partie de mes contraintes techniques pour des solutions que, je trouve personnellement, propres. L'API des MPs supportent maintenant sa création, sa mise à jour et quitter un ou plusieurs MP en même temps. Le tout étant refactorisé avec les anciennes vues, testé, documenté et la PR rebasé par rapport au dépôt officiel. Le travail est clean et ready pour la suite (d'ailleurs si vous voulez voir le taff, ma branche est par là).
Que reste-t-il à faire ?
Il y a encore du taff mais on avance. La journée d'aujourd'hui a été très productif et remotive pour la suite !
Salut tout le monde,
J'ai de bonnes nouvelles. Déjà, DevHugo a décidé de me donner un coup de main. Il est en bonne voie pour l'ajout d'un message dans un MP. Fonctionnellement, ça fait le boulot et c'est déjà testé. Il y a juste quelques petites mises à jour à faire pour rester cohérent avec le reste. Ce n'est donc pas encore fait mais quasi.
De mon côté, je me suis penché sur les petites choses un peu plus tricky, à savoir étendre les champs et afficher le markdown ou le html. Ces deux points sont maintenant mergés dans la branche refacto_mp de mon dépôt.
Pour vous donner des exemples :
Si nous lançons la requête suivante pour récupérer tous les MP d'un utilisateur connecté http://localhost:8000/api/mps/. Nous obtenons comme réponse :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | { "count": 1, "next": null, "previous": null, "results": [ { "id": 1, "title": "Comment on fait pour devenir staff ?", "subtitle": "C'est mon rêve !", "pubdate": "2013-12-21T13:20:30", "author": 3, "last_message": 1, "participants": [ 1, 2 ] } ] } |
Maintenant, si nous décidons d'étendre last_message et participants sur tous les messages. Nous lançons la requête http://localhost:8000/api/mps/?expand=last_message&expand=participants et obtenons la réponse :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | { "count": 1, "next": null, "previous": null, "results": [ { "id": 1, "title": "Comment on fait pour devenir staff ?", "subtitle": "C'est mon rêve !", "pubdate": "2013-12-21T13:20:30", "author": 3, "last_message": { "id": 1, "text": "Bonjour<br />On fait comment pour devenir staff svp ?", "text_html": "", "pubdate": "2013-12-21T13:20:30", "update": null, "position_in_topic": 1, "privatetopic": 1, "author": 3 }, "participants": [ { "id": 1, "username": "admin", "is_active": true, "date_joined": "2015-05-01T14:29:10.198638" }, { "id": 2, "username": "staff", "is_active": true, "date_joined": "2015-05-01T14:29:10.214454" } ] } ] } |
Nous pouvons voir que participants et last_message ont été étendu mais pas author. La solution est générique, marche pour toutes les méthodes GET de l'API des MPs et devrait, théoriquement, s'adapter à tous les modules.
Dorénavant, on peut utiliser l'en-tête X-Data-Format pour spécifier si nous voulons le contenu en Html ou en Markdown. Donc, si nous voulons un message en HTML ou en Markdown, suffit de renseigner l'en-tête.
Ca sent la fin, il reste l'ajout d'un message qui est presque terminé et l'édition d'un message si c'est le dernier d'un MP. Après quelques détails, je ferais la PR sur le dépôt officiel !
Voilà pour le topo du jour.
Salut à tous,
Je vois que les avancements plaisent. Ca ne poste pas beaucoup mais ça "plussoie". C'est bien mais j'aurais besoin de votre intervention aujourd'hui. Avant tout, sachez qu'il est maintenant possible d'éditer le dernier message d'un message privé et qu'une PR de Hugo sur mon dépôt est en cours de finition pour ajouter une réponse à un MP. La ZEP est donc à 2 doigts de se terminer !
Encore une fois, merci à vous tous ! Certes, ça a été moins enthousiaste que l'API des membres puisque c'était la toute première brique à l'API mais il en reste pas moins que vous avez tous participer aux spécifications de cette ZEP et, pour Hugo, dans la contribution technique qui, j'espère, ne sera pas sa dernière contribution à l'API. Il est vrai que je suis un peu exigeant quand on travaille avec moi et j'ai dû le renvoyer plusieurs fois revoir sa copie le pauvre.
Mais donc, pourquoi est-ce que j'ai besoin de votre avis ? Et bien, pour la suite ! L'API des MPs devrait faire sa PR sur le dépôt officiel début de la semaine prochaine si tout se passe bien et elle sera embarquée dans une prochaine release (sans doute celle de Juin). Cela laisse de temps pour rédiger les spécifications de la prochaine API ! J'aimerais donc savoir ce qui vous plairait comme API pour la prochaine étape :
J'écarte volontairement les modules des articles et des tutoriels puisque artragis et pierre-24 y travaillent avec acharnement sur la nouvelle version. Qui sait, ils seront peut-être motivé par après pour développer l'API !
Donc je suis ouvert à votre avis sur ma prochaine contribution pour Zeste de Savoir !
La ZEP-28 a pour objectif de changer assez profondément le fonctionnement des galeries, par conséquent, je ne suis pas pour que la prochaine brique de l'API les concerne.
En revanche, je ne dis pas non pour les forums : le petit coup de neuf qui devra précéder la mise en place de l'API ne peut que leur faire du bien.
La ZEP-28 a pour objectif de changer assez profondément le fonctionnement des galeries, par conséquent, je ne suis pas pour que la prochaine brique de l'API les concerne.
Ah oui tiens, j'étais passé à côté. Je rajoute la référence vers cette ZEP dans mon message. Merci !
Toi andro c'est quoi qui te motive le plus ? Le forum est probablement celle avec le plus d'impact mais demande aussi probablement beaucoup de travail.
Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte