ZEP-23 : Elaboration de l'API des MPs

a marqué ce sujet comme résolu.
Cartouche
ZEP 23
Titre Elaboration de l'API des MPs
Révision 4
Date de création 15 Janvier 2015
Dernière révision 19 Février 2015
Type Feature
Statut Validation

Contexte

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.

API des MPs

Objectif

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.

Représentations

Sujet d'un MP
Exemple d'objet
 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,
}
Colonnes
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
Message d'un MP
Exemple d'objet
 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"
    }
}
Colonnes
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

Etendre des objets

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.

Lister les MPs d'un membre

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • page : Affiche les MPs de la page voulue.
  • filter :
    • lu : Filtre tous les messages lus.
    • non-lu : Filtre tous les messages non lus.
    • date : Récupère les messages à partir de cette date.
  • sort :
    • creation : Tri la liste par date de création.
    • modification : Tri la liste par date de modification.
    • last-message : Tri la liste par date du dernier message.
    • titre : Tri par ordre alphabétique.
  • search :
    • titre : Recherche les conversations privées par leurs noms.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Afficher un MP donné

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant du message privé

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Création d'un nouveau MP

Fonctionnalité : Création d'un nouveau MP avec plusieurs participants

URL : http://api.zestedesavoir.com/mps/

Méthode : POST

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • participants : Liste des membres participants à la conversation
  • title : Titre du MP
  • subtitle : Sous-titre du MP (facultatif)
  • text : Contenu du MP.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Si un participant n'existe pas.

Permissions nécessaires :

  • Être authentifié

Edition d'un MP

Fonctionnalité : Ajoute un ou plusieurs participants dans un MP donné.

URL : http://api.zestedesavoir.com/mps/{id}/

Méthode : PUT

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant de la conversation
  • participants : Liste des membres à ajouter dans la conversation.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Si un participant n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Quitter une liste de MPs

Fonctionnalité : Se retirer d'une liste de conversations.

URL : http://api.zestedesavoir.com/mps/

Méthode : DELETE

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • pks : La liste des identifiants des conversations à quitter séparé par une virgule.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : L'un des MPs n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Quitter un MP

Fonctionnalité : Se retirer d'une conversation.

URL : http://api.zestedesavoir.com/mps/{id}/

Méthode : DELETE

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant de la conversation

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Lister les messages d'un MP donné

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant d'une conversation.
  • page : Affiche les MPs de la page voulue.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas ou la page n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Afficher le message d'un MP donné

Fonctionnalité : Renvoie les informations concernant un MP donné.

URL : http://api.zestedesavoir.com/mps/{id}/messages/{id-mes}/

Méthode : GET

Headers :

  • Authorization: Bearer < access_token >
  • X-Data-Format : Renseigne le format désiré pour le message (HTML ou Markdown)

Paramètres :

  • id : Identifiant d'une conversation
  • id-mes : Identifiant du message privé

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas ou le message n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Ajouter un nouveau message dans un MP

Fonctionnalité : Ajoute un message dans un MP de l'utilisateur.

URL : http://api.zestedesavoir.com/mps/{id}/messages/

Méthode : POST

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant d'une conversation
  • id-mes :
  • text : Contenu du message

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Editer un message dans un MP

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant d'une conversation
  • id-mes : Identifiant du message privé
  • text : Nouveau contenu du message

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs
+11 -0

Hey, Comme l'api des membres, je dis juste bravo. Je vais pouvoir l'intégrer au clemNotifier.

Juste une question (bête ?) concernant l'api (c'est ma première fois avec les apis de ce type), il faut faire une requête toutes les x secondes ou elle nous avertit d'un nouveau message ?

Encore bravo :)

+0 -0

Ravi de voir que l'API plaît.

Juste une question (bête ?) concernant l'api (c'est ma première fois avec les apis de ce type), il faut faire une requête toutes les x secondes ou elle nous avertit d'un nouveau message ?

Une API met simplement à disposition des ressources. Tu fais une requête à une adresse donnée et il se contente de renvoyer les données voulues. Pour être avertit, il faut un serveur de push et c'est quelque chose de différent d'une API.

PS : Il existe plusieurs genres d'API REST ? ^^

Sinon, je suis content de voir que la spec pour cette nouvelle API plait tellement. :)

+0 -0

Ca n'empêche pas que le module des tutos reste le plus gros module du site. Tout le refactoring que vous appliquez sur ce module sera bon à prendre mais il y aura encore du taff à faire dessus pour que cela convienne à l'API (des choses que vous ne pouvez pas prévoir maintenant).

Cela dit, nous n'y sommes pas encore et il y a d'autres modules tout aussi important. Celui ci, mine de rien, va permettre aux extensions de navigateurs de ne plus parser la page d'accueil pour récupérer les MPs de l'utilisateur. Il faudra toujours le faire pour les notifications malheureusement mais chaque chose en son temps. :)

+2 -0

Vraiment, il n'y a aucune remarque à faire sur la spécification de cette ZEP API ? Genre, au hasard parmi les choses pour lesquels je pensais qu'il y allait avoir débat :

  • Avoir une URL du type api.zestedesavoir.com/mps/, donc avec un "s" à mp alors qu'il n'en existe pas sur les URLs du site. D'un côté, nous avons le respect des conventions REST en rajoutant un "s", d'un autre nous avons une différence avec le site.
  • La méthode DELETE pour se retirer d'un MP alors que, concrètement, il ne s'agit pas d'un DELETE derrière cette requête.
  • Les exemples d'objet où nous affichons peut-être un peu trop d'information à propos d'une conversation ou d'un message.

Après, si tout ceci convient à tout le monde, je suis étonné mais c'est cool. Ca sera d'autant plus simple à mettre en oeuvre. ^^

+0 -0

•Avoir une URL du type api.zestedesavoir.com/mps/, donc avec un "s" à mp alors qu'il n'en existe pas sur les URLs du site. D'un côté, nous avons le respect des conventions REST en rajoutant un "s", d'un autre nous avons une différence avec le site.

Tu donnes toi même la réponse… Et au pire je propose qu'on se fie au tuto "REST et HATEOAS".

•La méthode DELETE pour se retirer d'un MP alors que, concrètement, il ne s'agit pas d'un DELETE derrière cette requête

Osef le sens est bien celui d'une suppression de la participation.

Perso je suis juste perplexe quant au fait d'envoyer le markdowb ET le HTML. Ca devrait être un paramètre à passer en querystring.

+0 -0

Il manque l'auteur dans la représentation du message d'un mp

edit: ah et aussi je pense qu'il faudrait une interface au niveau de la lecture des messages de MP, par exemple :

  • afficher tout les mp qui ont des messages non lus
  • pouvoir indiquer au serveur que l'utilisateur a lu un message

edit2: pas de possibilités de quitter plusieurs mp avec une seule requête

+0 -0

•Avoir une URL du type api.zestedesavoir.com/mps/, donc avec un "s" à mp alors qu'il n'en existe pas sur les URLs du site. D'un côté, nous avons le respect des conventions REST en rajoutant un "s", d'un autre nous avons une différence avec le site.

Tu donnes toi même la réponse… Et au pire je propose qu'on se fie au tuto "REST et HATEOAS".

Autant que toutes les URLs de l'api soient cohérentes et respectueuses des standard. Je vote aussi pour le "s".

•La méthode DELETE pour se retirer d'un MP alors que, concrètement, il ne s'agit pas d'un DELETE derrière cette requête

Osef le sens est bien celui d'une suppression de la participation.

l'url http://api.zestedesavoir.com/mps/{id}/ utilisé ave cla méthode DELETE, ça devrait supprimer le MP en question. Hors finalement, c'est bien de ça qu'il s'agit : supprimer le MP de sa boite à MP. S'il y a d'autres participants, eux l'ont toujours tant qu'ils ne le suppriment pas également. S'il n'y a pas d'autre participants, le MP est supprimé complètement. Donc c'est logique, même si dans certains cas, ce n'est pas une suppression pure et dure derrière.

Perso je suis juste perplexe quant au fait d'envoyer le markdowb ET le HTML. Ca devrait être un paramètre à passer en querystring.

artragis

Itou

  • Les exemples d'objet où nous affichons peut-être un peu trop d'information à propos d'une conversation ou d'un message.

Pourquoi avoir le dernier message quand tu récupères un topic ? A première vue ça ne me semble pas utile.

+0 -0

Pourquoi les messages ont des "pk" et les membres des "id" ? Au final, ça représente la même chose, une clé technique. Je pense qu'il faudrait uniformiser la dénomination des clés techniques.

(J'ai pas relu la ZEP-02, si la question a été soulevée là bas, my bad)

+0 -0

(le premier message ayant moins de 24h, tout le monde ne l'ont peut-etre pas encore vu ;) )

Eskimon

C'est la seule manière que j'ai trouvé pour pointer du doigt les choses sur lesquels j'avais des doutes. :-°

Perso je suis juste perplexe quant au fait d'envoyer le markdowb ET le HTML. Ca devrait être un paramètre à passer en querystring.

artragis

Itou

Taguan

J'ai pensé exactement comme toi au début. Puis, j'ai vu dans le modèle d'un MP que le texte markdown et HTML étaient tous les deux sauvegardés en base de données. J'ai alors jugé plus pertinent d'afficher directement les deux plutôt que de devoir faire 2 fois exactement la même remarque.

Le choix vous semble moins déconnant ou je fais fausse route ?

Il manque l'auteur dans la représentation du message d'un mp

poulp

Tout à fait, je rajoute ça dans une nouvelle révision que je proposerais prochainement (après avoir eu un peu plus de retour) !

  • afficher tout les mp qui ont des messages non lus

poulp

Avoir des filtres dans la liste des messages ? Très bonne idée. Je le rajouterais aussi dans la prochaine révision !

  • pouvoir indiquer au serveur que l'utilisateur a lu un message

poulp

Effectivement, tu soulèves un problème intéressant. Comment définir qu'un membre a lu un message ? J'aurais plutôt marqué un message comme lu lorsque on tente de le récupérer. Par exemple, si je demande le message avec l'id 123, ce même message sera marqué comme lu.

Qu'est ce que vous en pensez ?

edit2: pas de possibilités de quitter plusieurs mp avec une seule requête

poulp

Tout à fait, cela va venir dans une prochaine révision aussi !

  • Les exemples d'objet où nous affichons peut-être un peu trop d'information à propos d'une conversation ou d'un message.

Pourquoi avoir le dernier message quand tu récupères un topic ? A première vue ça ne me semble pas utile.

Taguan

Si un jour le front ne fait que se cabler sur l'API, il ne sera pas en mesure d'afficher le dernier message dans la liste des MPs d'un utilisateur. C'est comme ça que j'avais pensé la chose.

Cela te semble déconnant ?

Pourquoi les messages ont des "pk" et les membres des "id" ? Au final, ça représente la même chose, une clé technique. Je pense qu'il faudrait uniformiser la dénomination des clés techniques.

(J'ai pas relu la ZEP-02, si la question a été soulevée là bas, my bad)

btw03

Non, tu soulèves un bug présent dans l'API des membres ! Cela doit être pk partout en fait. Merci bien. :)

+0 -0
  • Les exemples d'objet où nous affichons peut-être un peu trop d'information à propos d'une conversation ou d'un message.

Pourquoi avoir le dernier message quand tu récupères un topic ? A première vue ça ne me semble pas utile.

Taguan

Si un jour le front ne fait que se cabler sur l'API, il ne sera pas en mesure d'afficher le dernier message dans la liste des MPs d'un utilisateur. C'est comme ça que j'avais pensé la chose.

Cela te semble déconnant ?

Je suis d'accord avec Taguan: Pour moi, on devrait avoir uniquement ID + lien + timestamp. Pourquoi, parce que ça suffit pour déterminer s'il y a, ou non, un ou plusieurs nouveaux messages, et ainsi faire les requêtes nécessaires pour récupérer ces nouveaux messages. Une fois que la page est chargée, 1 ou 2 requêtes de plus pour récupérer les MPs, c'est pas hyper gourmand…

http://api.zestedesavoir.com/mps/

http://api.zestedesavoir.com/mps/{id}/messages/

Pour ces deux endpoints, on devrait avoir en paramètres un timestamp pour récupérer les messages à partir d'une certaine date. Cela permet de récupérer uniquement les "nouveaux" messages, et uniquement les thread ayant de nouveaux messages, et permet donc d'optimiser la récupération de nouveaux MPs en "temps réel", lorsque le client a déjà une ancienne liste de MPs.

http://api.zestedesavoir.com/mps/

Ici, il faudrait la possibilité de "filtrer" et de changer classer autrement. Filtrer par participants, et par "lu/non-lu", et classer par date de dernier message, de création, de modification, et par nom. On doit aussi pouvoir "rechercher" dans les MPs, en filtrant par nom.

Pour l'objet "message", je verrais plutôt une clé "body", plutôt que "text"… Pareil, pour "pubdate" et "update", je verrais plutôt "created_at" et "updated_at". Je sais pas si c'est des noms qui ont été choisi à cause du schéma de la base de donnée, mais je les trouves pas forcément géniaux ^^ (les noms que je proposent sont plus ou moins les mêmes que ceux de l'API GitHub, Twitter et Facebook)

+0 -0

Andr0, tu penses que l'api va sortir quand ?

C'est juste impossible à prévoir pour plusieurs raisons :

  1. Je ne serais potentiellement pas le seul développeur à travailler sur l'API. N'importe qui peut créer une ZEP fille à la ZEP 2 pour la spécification de l'API d'un nouveau module et s'y atteler. Le développement de l'API du premier module était justement destiné a devenir une référence pour que tous les développeurs puissent s'en inspirer.
  2. J'avance à mon rythme (avec les personnes qui m'entourent). J'ai mis un peu plus d'un mois pour l'API des membres qui est le module le plus simple de Zeste de Savoir. Bien évidemment, j'ai perdu du temps parce que j'ai dû monter en compétence dans Django et sa librairie pour concevoir des APIs en même temps mais d'autres modules sont bien plus gros et vont me demander tout autant de temps, voire plus.
  3. Il peut y avoir n'importe quel imprévu par le fait que nous développons cette API sur notre temps libre.

Cela dit, très clairement, une API complète ne sera pas mise en oeuvre avant plusieurs mois, surtout si personne ne veut faire des APIs en parallèle à celles que je développe.

Je suis d'accord avec Taguan: Pour moi, on devrait avoir uniquement ID + lien + timestamp. Pourquoi, parce que ça suffit pour déterminer s'il y a, ou non, un ou plusieurs nouveaux messages, et ainsi faire les requêtes nécessaires pour récupérer ces nouveaux messages. Une fois que la page est chargée, 1 ou 2 requêtes de plus pour récupérer les MPs, c'est pas hyper gourmand…

Si j'allège le dernier message d'une conversation privée, je pense ne renvoyer que son identifiant alors (ce qui est le strict nécessaire pour la nouvelle requête). Je trouve ça simplement dommage de ne pas le renvoyer au complet dans la foulée. De toute façon, je dispose de cette information complète lorsque quelqu'un fera une requête pour obtenir une conversation. Si on opte pour votre solution : Du côté client, il faut faire deux requêtes HTTP. Du côté serveur, il faut faire 2 fois la même requête en base de données. Alors qu'avec la solution actuelle : une requête suffit des 2 côtés.

Mais votre solution semble convenir à plus de monde. Ca viendra dans une prochaine révision.

http://api.zestedesavoir.com/mps/

http://api.zestedesavoir.com/mps/{id}/messages/

Pour ces deux endpoints, on devrait avoir en paramètres un timestamp pour récupérer les messages à partir d'une certaine date. Cela permet de récupérer uniquement les "nouveaux" messages, et uniquement les thread ayant de nouveaux messages, et permet donc d'optimiser la récupération de nouveaux MPs en "temps réel", lorsque le client a déjà une ancienne liste de MPs.

http://api.zestedesavoir.com/mps/

Ici, il faudrait la possibilité de "filtrer" et de changer classer autrement. Filtrer par participants, et par "lu/non-lu", et classer par date de dernier message, de création, de modification, et par nom. On doit aussi pouvoir "rechercher" dans les MPs, en filtrant par nom.

Comme le mentionnait quelqu'un avant toi, des paramètres de filtre seront intégrés à la prochaine révision. Par contre, nous intégrerons là une nouvelle fonctionnalité par rapport au site puisque le site ne le permet pas à ce jour.

Pour l'objet "message", je verrais plutôt une clé "body", plutôt que "text"… Pareil, pour "pubdate" et "update", je verrais plutôt "created_at" et "updated_at". Je sais pas si c'est des noms qui ont été choisi à cause du schéma de la base de donnée, mais je les trouves pas forcément géniaux ^^ (les noms que je proposent sont plus ou moins les mêmes que ceux de l'API GitHub, Twitter et Facebook)

Sandhose

Là, c'est lié à un "binding" avec les champs dans le modèle des MPs. Je peux les changer mais j'aimerais vraiment éviter une incohérence entre le modèle et l'API.

+2 -0

Andr0, tu penses que l'api va sortir quand ?

C'est juste impossible à prévoir pour plusieurs raisons :

  1. Je ne serais potentiellement pas le seul développeur à travailler sur l'API. N'importe qui peut créer une ZEP fille à la ZEP 2 pour la spécification de l'API d'un nouveau module et s'y atteler. Le développement de l'API du premier module était justement destiné a devenir une référence pour que tous les développeurs puissent s'en inspirer.
  2. J'avance à mon rythme (avec les personnes qui m'entourent). J'ai mis un peu plus d'un mois pour l'API des membres qui est le module le plus simple de Zeste de Savoir. Bien évidemment, j'ai perdu du temps parce que j'ai dû monter en compétence dans Django et sa librairie pour concevoir des APIs en même temps mais d'autres modules sont bien plus gros et vont me demander tout autant de temps, voire plus.
  3. Il peut y avoir n'importe quel imprévu par le fait que nous développons cette API sur notre temps libre.

Cela dit, très clairement, une API complète ne sera pas mise en oeuvre avant plusieurs mois, surtout si personne ne veut faire des APIs en parallèle à celles que je développe.

D'accord. Je parle, je parle… Je t'envoie un MP pour pouvoir développer l'api.

+0 -0

Je vous propose cette seconde révision :

Cartouche
ZEP 23
Titre Elaboration de l'API des MPs
Révision 2
Date de création 15 Janvier 2015
Dernière révision 22 Janvier 2015
Type Feature
Statut Rédaction

Contexte

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.

API des MPs

Objectif

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.

Représentations

Sujet d'un MP
Exemple d'objet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "pk": 654321,
    "title": "Titre du MP",
    "subtitle": "Sous-titre du MP",
    "pubdate": "1977-04-22T06:00:00Z",
    "author": {
        "id": 42,
        "username": "Clem",
        "email": "clem@zds.com"
    },
    "participants": [
        {
            "id": 42,
            "username": "Clem"
        },
        {
            "id": 5,
            "username": "Andr0"
        }
    ],
    "last_message": 123456
}
Colonnes
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
Message d'un MP
Exemple d'objet
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "pk": 123456,
    "privatetopic": 654321,
    "text": "# Contenu du message",
    "text_html": "<h1>Contenu du message</h1>",
    "pubdate": "1977-04-22T06:00:00Z",
    "update": "1977-04-22T06:00:00Z",
    "position_in_topic": 1,
    "author": {
        "pk": 42,
        "username": "Clem"
    }
}
Colonnes
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

Lister les MPs d'un membre

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • page : Affiche les MPs de la page voulue.
  • filter :
    • lu : Filtre tous les messages lus.
    • non-lu : Filtre tous les messages non lus.
    • date : Récupère les messages à partir de cette date.
  • sort :
    • creation : Tri la liste par date de création.
    • modification : Tri la liste par date de modification.
    • last-message : Tri la liste par date du dernier message.
    • titre : Tri par ordre alphabétique.
  • search :
    • titre : Recherche les conversations privées par leurs noms.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Afficher un MP donné

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant du message privé

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Création d'un nouveau MP

Fonctionnalité : Création d'un nouveau MP avec plusieurs participants

URL : http://api.zestedesavoir.com/mps/

Méthode : POST

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • participants : Liste des membres participants à la conversation
  • title : Titre du MP
  • subtitle : Sous-titre du MP (facultatif)
  • text : Contenu du MP.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Si un participant n'existe pas.

Permissions nécessaires :

  • Être authentifié

Edition d'un MP

Fonctionnalité : Ajoute un ou plusieurs participants dans un MP donné.

URL : http://api.zestedesavoir.com/mps/{id}/

Méthode : PUT

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant de la conversation
  • participants : Liste des membres à ajouter dans la conversation.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Si un participant n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Quitter une liste de MPs

Fonctionnalité : Se retirer d'une liste de conversations.

URL : http://api.zestedesavoir.com/mps/

Méthode : DELETE

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • pks : La liste des identifiants des conversations à quitter séparé par une virgule.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : L'un des MPs n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Quitter un MP

Fonctionnalité : Se retirer d'une conversation.

URL : http://api.zestedesavoir.com/mps/{id}/

Méthode : DELETE

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant de la conversation

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Lister les messages d'un MP donné

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant d'une conversation.
  • page : Affiche les MPs de la page voulue.

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas ou la page n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Afficher le message d'un MP donné

Fonctionnalité : Renvoie les informations concernant un MP donné.

URL : http://api.zestedesavoir.com/mps/{id}/messages/{id-mes}/

Méthode : GET

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant d'une conversation
  • id-mes : Identifiant du message privé

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas ou le message n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Ajouter un nouveau message dans un MP

Fonctionnalité : Ajoute un message dans un MP de l'utilisateur.

URL : http://api.zestedesavoir.com/mps/{id}/messages/

Méthode : POST

Headers :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant d'une conversation
  • id-mes :
  • text : Contenu du message

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs

Editer un message dans un MP

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 :

  • Authorization: Bearer < access_token >

Paramètres :

  • id : Identifiant d'une conversation
  • id-mes : Identifiant du message privé
  • text : Nouveau contenu du message

Codes HTTP :

  • 200 : La réponse est renvoyée sans problème.
  • 400 : Dès qu'il y a un problème avec les paramètres de la requête.
  • 401 : Problème avec l'authentification.
  • 403 : Pas les permissions nécessaires.
  • 404 : Le MP n'existe pas.

Permissions nécessaires :

  • Être authentifié
  • Être auteur ou dans les participants des MPs
+3 -0
Connectez-vous pour pouvoir poster un message.
Connexion

Pas encore membre ?

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