Carnet Wiki

API de conversion de fichiers

Version 5 — Octobre 2013 severo

Pour réfléchir autour de l’idée d’une API et d’un système client/serveur pour la conversion de fichiers (documents, images, son, vidéos).

Ce qu’on veut pouvoir faire

Actions souhaitées avec l’API
Liste des actions souhaitées avec l’API
Fichier en entréeActionRésultat
Documents doc ou odt, rtf...
doc convertir en odt odt
doc convertir en PDF pdf
doc générer un vignette (image de la première page) png
doc générer une image par page plusieurs png
doc extraire le texte brut texte
doc convertir en HTML (avec option pour intégrer les images en base64) html
Documents PDF ou tiff multipage, ps, epub ?
pdf générer un vignette (image de la première page) png
pdf générer une image par page plusieurs png
pdf extraire le texte brut (avec option OCR si aucun texte n’est inclus directement) texte
pdf convertir en HTML (avec option pour intégrer les images en base64) html
pdf convertir en doc (éventuellement) doc
Images
png convertir en un autre format jpg
png extraire le texte brut par OCR texte
Sons
mp3 convertir en un autre format ogg
mp3 extraire le texte correspondant (reconnaissance vocale, on peut rêver) texte
Vidéos
avi convertir en un autre format ogv
avi extraire le texte correspondant (reconnaissance vocale, on peut rêver) texte

Client

Client et Serveur Serveur

Pour chacune de ces actions, le client donne accès au fichier (par URL ou par transfert) au serveur. Le serveur effectue l’action. Finalement il met à disposition du client une URL pour récupérer le résultat, durant le temps nécessaire à son téléchargement. Après quelques heures (paramètre à définir), le résultat est effacé et l’URL retourne un code d’erreur.

En retour de sa demande de conversion, le client reçoit une URL contenant par exemple une clé unique. Durant le temps de la conversion, l’URL retourne un statut HTTP qui indique que la conversion n’est pas fini. Lorsque le résultat est prêt, l’URL retourne le résultat. Le client doit donc accéder régulièrement à l’URL pour savoir si la conversion est terminée ou non.

L’URL peut donner accès au fichier à télécharger directement, ou fichier de données (par exemple JSON) qui indique l’URL où télécharger le ou les fichiers, ou éventuellement qui contient lui même le résultat.

Dans le cas où le serveur est aussi installé dans le même site, le client peut court-circuiter l’API et accéder directement aux commandes système.

Le serveur authentifie le client, et donne lui accès à tout ou partie des actions. On peut éventuellement imaginer que le serveur publie la liste des actions dont il est capable (méta-données décrivant le contenu du service et les paramètres acceptés).

Il faut se poser la question de savoir si un seul plugin peut fournir l’API pour toutes les actions de conversion, ou s’il faut une API différente pour chaque type de fichier, en raison des paramètres différents (résolution pour les images, échantillonage ? pour le son, ...).

Serveur

Serveur

Le serveur doit savoir :

  • décoder la commande du client (JSON -> action + liste de paramètres)
  • authentifier le client et autoriser ou non l’action
  • récupérer un fichier (par upload, ou en téléchargeant depuis une URL)
  • effectuer l’action
  • générer une URL spécifique au client (pour qu’il teste l’avancement de l’action, et qu’il récupère le résultat)
  • mettre le résultat selon la forme demandée par le client (téléchargement direct, encapsulation résultat -> JSON)
  • garder le résultat à disposition durant X temps, puis l’effacer

Client

Client

Le client doit savoir :

  • forger sa commande (action + liste de paramètres -> JSON)
  • s’authentifier sur le serveur
  • envoyer le fichier (par upload ou en fournissant une URL)
  • récupérer son URL spécifique
  • utiliser régulièrement l’URL spécifique pour connaître l’avancement de l’action
  • récupérer le résultat lorsque l’action est terminée
  • extraire le résultat (JSON -> résultat)

Les paramètres envoyés au serveur peuvent être (voir plugin oficina) :

  • email : pour identifier l’utilisateur
  • key : pour vérifier les droits
  • url : où télécharger le fichier
  • format : ce que l’URL spécifique retournera
    • json : résultat encapsulé en format JSON
    • dl : téléchargement direct du résultat
    • vide : une page de test avec un formulaire (contenant tous ces champs) et le résultat affiché en dessous
  • filter : paramètre pour la conversion doc -> html (traitements spécifiques)
  • images inline : paramètre pour la conversion doc -> html (inclure les images en base64 dans le code HTML)

Est-ce qu’utiliser une boucle DATA a un sens pour récupérer les données sur le serveur ? Avec un critère clé ou url_specifique ?

Ce

Ce que l’API ne fera pas pas

  • publier le fichier converti sur le serveur. Le résultat ne sera accessible que par le client. Éventuellement, s’il existe un autre plugin de publication à distance (genre CDN), on pourra les coupler pour que la conversion d’une vidéo, par exemple, retourne en résultat un code HTML d’embed, ou une URL oembed, la visualisation de la vidéo convertie se faisant pour les visiteurs sur le serveur « CDN ».
  • le café

Comment le faire ?

Plugins

Plugins en relation relation

Les plugins existants peuvent être reliés : doc2img, spipmotion, facd, ocr, oficina, mediaspip_core, fulltext