ZEP-45 : API des galeries

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.

Cette ZEP permet de créer une API pour gérer les galeries. Le site Zeste de Savoir pourrait l'utiliser pour permettre d'uploader des images depuis l'éditeur markdown. Les applications externes pourrait l'utiliser pour permettre la gestion des galeries dans leurs applications (zest-writter par exemple).

API des galeries

Objectif

Elle permettra de :

• Lister, ajouter, modifier, quitter des galeries ;
• Lister, ajouter des membres à leurs galeries ;
• Téléverser des images et des archives d'images ;
• Modifier et supprimer les informations d'une image.

Représentation

Exemple d'objet galerie

 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

{
     "pk": 1,
     "title": "Titre de la galerie",
     "subtitle": "Sous-titre de la galerie",
     "pubdate": "1977-04-22T06:00:00Z",
     "updatedate": "1977-04-22T06:00:00Z",
     "participants": [
         {
            "pk": 42,
            "username": "Clem",
            "self": "http://api.zestedesavoir.com/membres/42",
            "permissions": [
               "read": true,
               "write": true,
            ]
         },
         {
            "pk": 5,
            "username": "Clin d'oeil à Andr0",
            "self": "http://api.zestedesavoir.com/membres/5"
            "permissions": [
               "read": true,
            ]
         }
      ],
      "permissions": [
       "read": true,
       "write": true,
      ],
      "linkToContent": 137
}

Colonnes

Exemple d'objet d'image

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
     "pk": 1,
     "title": "Titre de l'image",
     "legend": "Legende de l'image",
     "self": "Lien vers l'image. ex: http://zestedesavoir.com/Andr0/droid.jpg",
     "pubdate": "1977-04-22T06:00:00Z",
     "updatedate": "1977-04-22T06:00:00Z",
     "thumbnail": "Lien vers la miniature de l'image. ex: http://zestedesavoir.com/Andr0/droid-miniature.jpg",
     "permissions": [
       "read": true,
       "write": true,
      ],
      "linkToContent": 137
}

Colonnes

Lister les différentes galeries

Fonctionnalité : Renvoie une liste paginée des galeries auquel le membre connecté à les droits.

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

Méthode : GET

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• page : Affiche les galeries de la page voulue.

• sort :

  • creation : Tri la liste par date de création.
  • modification : Tri la liste par date de modification.
  • titre : Tri par ordre alphabétique.

• search :

  • titre : Recherche des galeries par leurs nom.

Codes HTTP :

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

Permissions nécessaires : Être authentifié.

Afficher une galerie

Fonctionalité : Renvoie les informations d'une galerie.

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

Méthode : GET

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• page : Affiche les galeries de la page voulue.

• sort :

  • creation : Tri la liste par date de création.
  • modification : Tri la liste par date de modification.
  • titre : Tri par ordre alphabétique.

• search :

  • titre : Recherche des galeries par leurs nom.

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: La galerie n'existe pas.

Permissions nécessaires : Être authentifié, avoir les droits sur la galerie.

Ajouter une galerie

Fonctionalité : Permet d'ajouter une galerie.

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

Méthode : POST

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• title: Le titre de la galerie
• subtitle: Le sous titre de la galerie
• participants: liste des membres à ajouter dans la galerie.

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 membre n'existe pas.

Permissions nécessaires : Être authentifié.

Modifier une galerie

Fonctionalité : Permet de modifier le titre et le sous-titre d'une galerie.

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

Méthode : PUT

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• title: Le titre de la galerie
• subtitle: Le sous titre de la galerie
• participants: liste des membres à ajouter dans la galerie.

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é, avoir les droits nécessaires sur la galerie.

Quitter des galeries

Fonctionalité : Permet de quitter des galeries.

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

Méthode : DELETE

Headers :

• Authorization: Bearer < access_token >

Paramètres :

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

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 une galerie n'existe pas.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie, la galerie n'est pas celle d'un tutoriel ou d'un article si il ne reste qu'une seule personne dans la galerie.

Quitter une galerie

Fonctionalité : Permet de quitter une galerie.

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

Méthode : DELETE

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie

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 une galerie n'existe pas.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie, la galerie n'est pas celle d'un tutoriel ou d'un article si il ne reste qu'une seule personne dans la galerie.

Lister les différentes images d'une galerie

Fonctionnalité : Renvoie une liste paginée des images d'une galerie auquel le membre connecté à les droits.

URL : http://api.zestedesavoir.com/galeries/{id}/images/

Méthode : GET

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id : id de la galerie.
• page : Affiche les images d'une galerie de la page voulue.

• sort :

  • creation : Tri la liste par date de création.
  • modification : Tri la liste par date de modification.
  • titre : Tri par ordre alphabétique.

• search :

  • titre : Recherche des images par leurs nom.

Codes HTTP :

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

Permissions nécessaires : Être authentifié.

Lister les informations d'une image

Fonctionalité : Permet de lister les différentes information d'une image

URL : http://api.zestedesavoir.com/galeries/{id}/images/{idimage}

Méthode : GET

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• idimage: L'identifiant de l'image

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 une image n'existe pas.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie.

Ajouter une image

Fonctionalité : Permet d'ajouter une image à la galerie.

URL : http://api.zestedesavoir.com/galeries/{id}/images

Méthode : POST

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• title: Titre de l'image
• legend: La légende de l'image
• image: L'image en base-64 (cf: débat)

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.
• 413 : L'image est trop volumineuse.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie.

Mettre à jour une image

Fonctionalité : Permet de mettre à jours une image à la galerie.

URL : http://api.zestedesavoir.com/galeries/{id}/images/{idimage}

Méthode : PUT

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• idimage: L'identifiant de l'image
• title: Titre de l'image
• legend: La légende de l'image
• image: L'image en base-64 (cf: débat)

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 une image n'existe pas.
• 413 : L'image est trop volumineuse.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie.

Supprimer des images

Fonctionalité : Permet de supprimer des images de la galerie.

URL : http://api.zestedesavoir.com/galeries/{id}/images/

Méthode : DELETE

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• idimage: L'identifiant de l'image
• pks: Liste des identifiants des images à supprimer

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 une image n'existe pas.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie.

Supprimer une image

Fonctionalité : Permet de supprimer une image de la galerie.

URL : http://api.zestedesavoir.com/galeries/{id}/images/{idimage}

Méthode : DELETE

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie
• idimage: L'identifiant de l'image

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 une image n'existe pas.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie.

Upload d'une archive d'image

Fonctionalité : Permet d'upload des images à travers le téléversement d'une archive.

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

Méthode : POST / Multipart

Headers :

• Authorization: Bearer < access_token >

Paramètres :

• id: L'identifiant de la galerie

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.
• 413 : L'archive est trop volumineuse.

Permissions nécessaires : Être authentifié, avoir les droits nécessaires sur la galerie.

Débat:

La question est de savoir comment l'upload d'image marchera, je vois trois solutions:

• Multipart avec du JSON en payload
• Base64
• Envoyer le titre et la légende dans une première requête, le serveur retourne un identifiant unique de transaction. Le client envoi une autre requête avec l'image et l'identifiant généré avant.

Source: - Edition ce soir.

Edit: Correction orthographe, ajout des codes 400 et 413. Edit 2: Ajout du tag ZEP

Je pense qu'avant de faire l'API es galeries il faut revoir une partie du code.

J'ai visé iso-fonctionalité. Après y'avais une autre ZEP pour les améliorations sur les galeries.

C'est vrai que le code est pas génial, si je peut sans tout casser, refactorer, je le ferais.

Y'a des comportements bizarre, je suis d'accord, notamment,

• Supprimer une galerie, quand on est membre, supprime vraiment la galerie, on devrait avoir la notion de "quitter" une galerie.
• On ne peut pas supprimer des membres d'une galerie (c'est comme les mp, alors que la, pas de raison).
• Fonctionnalité sympa: ajouter des galeries dans des galeries.
• Confusion des notions de sous-titre et de legend.
• …

My bad, je me faisais la main sur CBV

J'avais un mauvais souvenir, je pensais même pas que c'était en CBV. C'est cool alors.

Quelques remarques en vrac :

• Dans les objectifs, il faut prévoir de quitter une galerie.

Ok, pas de souci, mais comme c'est pas le cas aujourd'hui, ça rajoute du travail .

• Représentation des galeries doit comporter les permissions aussi (tout comme les membres participants).

Je ne suis pas sur de comprendre. Dans le cas d'utilisation, où l'utilisateur choisit de lister ses galeries, il doit avoir les permissions associés à ses galeries ? Si c'est ça, ok, pas de souci.

• Représentation des images d'une galerie doit comporter les permissions aussi.

Dans le model Django, Image, on a pas la notion de droit sur l'image mais sur la galerie. On peut répeter les droits de la galerie sur chaque images dans la réponse. Je suis plutôt pour dans l'idée, maintenant, faut voir comment on fait ça, et ce que ça a comme impact.

• Quand tu affiches une galerie, tu n'affiches pas la liste des images. Il faut une URL supplémentaire du style /gallery/{id}/images/.

Ce que j'avais pensé au départ, c'était quand tu fait /gallery/{id}/, tu récupère les infos d'une galerie et, en plus la liste paginé des images de la galerie. C'est vrai que c'est un peu pourri comme truc. Je pense que c'est mieux de faire deux endpoint.

• La méthode HTTP pour ajouter une galerie est POST et pas ADD.

Ok.

• Quand tu ajoutes une galerie, cela pourrait être intéressant de fournir une image aussi.

Cela pourrait être intéressant, mais comme je ne sais pas sur qu'elle solution, on va choisir pour l'upload d'image. Je ne peut pas donner vraiment mon avis.

• La méthode HTTP pour ajouter une image à une galerie est POST et pas ADD.

Ok

• Quand tu veux supprimer des images d'une galerie, tu ne spécifies pas l'identifiant d'une image mais de plusieurs (mauvais paramètres).

Ok

Envoyer le titre et la légende dans une première requête, le serveur retourne un identifiant unique de transaction. Le client envoi une autre requête avec l'image et l'identifiant généré avant.

Tout dans une requête.

Ok, mais il reste encore à choisir entre deux solutions ^^.

J'édite la spec dans la semaine.

J'ai effectué tous les changements demandés sauf « Quand tu ajoutes une galerie, cela pourrait être intéressant de fournir une image aussi. », que j'ai mis de côté, on pourra en discuter quand on aura choisi la méthode d'upload. Je pense que c'est pas prudent de s'engager sur cette fonctionnalité alors qu'elle n'est pas indispensable mais juste sympa.
J'ai viré la possibilité de supprimer une galerie, je ferais les modifications pour que sur le site le bouton supprimer une galerie, se transforme en « quitter une galerie ».

J'avais pensé à un cas d'utilisation qui ne serait pas réglé par les specs d'API aujourd'hui, les applications externes peuvent avoir besoin de savoir si tel galerie est lié à tel contenu. Je pense qu'il faudrait rajouter cela, vous en pensez quoi ?

Dans les objectifs, il faut prévoir de quitter une galerie.

+ 1. C'est une bonne idée. Il faudra par contre prévoir le cas d'une galerie liée à un contenu. Il faudrait qu'il soit impossible de quitter une galerie si elle est liée à un contenu dont on est l'auteur.

J'ai rajouté un attribut linkToContent dans l'objet galerie et image qui indique l'id du contenu auquel est lié la galerie ou l'image. L'absence de cet attribut signifie que la galerie est lié à aucun contenu.

J'ai rajouté une petite phrase dans les droits nécessaires.

Fonctionalité : Permet de quitter des galeries.

Ici il y'a une petite question à se poser. Si parmi la liste des galleries à quitter, il existe une galerie que je n'ai pas le droits de quitter (si elle est liée à un contenu par exemple), que fait-on ?

1. On supprime uniquement les galeries autorisées ? et on renvoi un json avec les liste des galléries en échec ?
2. On ne supprime aucune des galeries et on renvoi un message d'erreur avec les galeries qu'on ne peut pas supprimer ?

Je n'ai pas pris le temps de mesurer l'impact de l'une ou l'autre solution, mais ça serait pas mal de répondre à la question.

C'est une question intéressante, personnellement, je pense que le plus simple est de prendre la deuxième option, « On ne supprime aucune des galeries et on renvoi un message d'erreur avec les galeries qu'on ne peut pas supprimer ». Je pense que c'est la solution, la plus simple et elle est en adéquation avec ce qu'on fait pour l'api des mps (j'ai relu très rapidement, à confirmer).

Note que la question est la même pour le paragraphe "Upload d'une archive d'image". On fait quoi s'il y'a une seule image en l'intérieur de l'archive qui est problématique ?

Je partirait sur la même solution. Après ça reste mon avis.

Il faudrait que l'API renvoi ici l'url de la nouvelle image (car l'url est censée changer à chaque mise à jour)

Bonne remarque. On peut retourner l'objet Image en entier, ça serait plus simple, pour les deux côtés, même si un peut moins performant.

Il semble manquer le endpoint qui permet de faire un GET sur une seule image. ça pourrait nous être utile par exemple pour obtenir les versions normales/miniatures/etc d'une image.

Bonne remarque, je rajouterai ça lors de la prochaine édition.

De tête, je dirais que le code est idiot et importe tout ce qu'il peut importer (le code est rempli de continue).

Je trouve que le comportement actuel, est pas super. Si je met à la place d'un auteur, je préférerai (bien que j'imagine que c'est une question de gout) que rien ne soit uploadé. Si j'ai 100 images, j'aurai pas envie de regarder à la main quels images sont passé et lesquels ne le sont pas.
On peut en profiter pour changer le comportement actuel.

L'implémentation d'aujourd'hui est un peu dangereuse, du coup, je pense que je vais ré-écrire une petite partie:

• Imagine que quelqu'un upload un fichier de 6 tera avec un nom qui ferait planté le os.remove(ph_temp). On aurait un fichier de 6 tera, sur le disque dur du serveur .
• Si le fichier est trop lourd, on a créé un fichier temporaire mais on l'a pas supprimé.
• Des images bombs, normalement on est bon mais ça vaut toujours le coût de tester pour voir (au moins un tu ?).

J'ajouterai que le code d'import d'image pour la galerie et celui des contenus n'est exactement pas le même (oh, la méchante duplication de code que voilà), et que du coup, ça serait sympa d'uniformiser ça et d'employer la même fonction partout, sinon on va avoir des surprises

Tu as tout à fait raison. Je vais faire ça.

L'implémentation d'aujourd'hui est un peu dangereuse, du coup, je pense que je vais ré-écrire une petite partie […]

Ça se tient. Maintenant, je suis pour supprimer ce qui ne peut être uploadé, mais pas forcément pour ne pas importer le reste de l'archive le cas échéant, c'est déjà chiant comme ça d'importer des images, autant ne pas avoir à recommencer avec ce qui fonctionne.

… Après, c'est vrai que c'est plus pratique d'importer le tout en une fois, pour pas faire de doublon si le mec corrige l'archive pour virer l'image fautive mais laisse les autres images intactes.

Ça se tient. Maintenant, je suis pour supprimer ce qui ne peut être uploadé, mais pas forcément pour ne pas importer le reste de l'archive le cas échéant, c'est déjà chiant comme ça d'importer des images, autant ne pas avoir à recommencer avec ce qui fonctionne.

… Après, c'est vrai que c'est plus pratique d'importer le tout en une fois, pour pas faire de doublon si le mec corrige l'archive pour virer l'image fautive mais laisse les autres images intactes.

Pour le problème de doublon, ce qu'on peut faire, c'est de stocker le hash du fichier lors de l'insertion d'une image. Lors de l'upload, on hash le fichier image et on regarde dans la base de donnée, si on n'a pas le même hash.

Petite digression, les hash des images publiés pourrait être stocké dans le manifest et on résout ainsi notre souci de gestion de version des images.

J'ai ajouté une partie pour lister les informations d'une image.

Je propose, que aucune action ne soit réalisé, si on a un souci avec au moins une des informations de la requête. Sauf dans le cas de l'upload du zip d'image, ou dans ce cas là, on upload tout ce qu'on peut.

Reste le débat, qui semble intéresser personne sur comment on upload: soit en Multipart avec du JSON en payload ou en Base64.

A vous les micros, les clémentines !

en Multipart avec du JSON en payload

… Beurk, non ? Je préférerai Base64.