Retour : page principale > sommaire eFlore v5 > eFlore API v0.1

eFlore Api v0.1 : Wiki


Format de base des URLs des services
Afin, que l'ensemble des services des différents projets soit interopérables la version de l'api sera définie pour l'ensemble des projets. L'URL de base des services sera la suivante : http://mon-domaine.org/mon-wikini/api/rest/#ressources
  • * "ressources" : le nom de la ressource demandé (la première ressource correspond au nom du fichier du service).

Cette URL pointera en réalité, dans un dossier :
/mon-wikini/tools/api/modules/#versionApi/#nomDuService.php
où :
  • #versionApi : correspond à la version de Wikini
  • #nomDuService : correspond au fichier du service demandé

Méthodes et codes de retour
Cette API doit retourner lorsque la méthode HTTP GET est utilisée des réponses HTTP ayant pour code :
  • 200 "OK" : requête traitée avec succès. Par défaut, ce code sera retourné avec la réponse.
  • 301 "Moved Permanently" : document déplacé de façon permanente. À utiliser quand on sait qu'une ressource a été supprimée et que l'on connait la ressource qui la remplace. L'adresse de la nouvelle ressource devrait être indiquée.
  • 400 "Bad Request" : la syntaxe de la requête est erronée. À utiliser quand les paramètres passés dans la requête sont contradictoires et qu'il est impossible de déterminer précisément la ressource demandée par le client.
  • 404 "Not Found" : document non trouvé. À utiliser quand la ressource demandée est introuvable. Par exemple, l'identifiant passé dans l'URL n'existe pas dans la base de donnée.
  • 410 "Gone" : la ressource est indisponible et aucune adresse de redirection n’est connue. À utiliser quand on sait qu'une ressource a été supprimée et qu'il n'y a pas de nouvelle ressource correspondante.
  • 500 "Internal Server Error" : erreur interne du serveur. Une erreur de programmation du service devrait retourner ce type de code.
  • 501 "Not Implemented" : fonctionnalité réclamée non supportée par le serveur. À utiliser quand un client demande un service non disponible.
  • 503 "Service Unavailable" : service temporairement indisponible ou en maintenance. Ce code devrait être renvoyer en cas de travaux de maintenance, migration... de l'API.

Descriptions des paramètres communs aux différentes ressources
Ces paramètres sont optionnels et sont passés après le signe "?" dans l'URL pour les requêtes de type GET.
  • masque : filtre la liste en fonction d'un masque de recherche portant sur le titre de la page, sont contenu ou le contenu d'un commentaire.
Ces paramètres sont optionnels et sont passés après le signe "?" dans l'URL.
  • masque : par défaut, filtre la liste en fonction d'un masque de recherche portant sur le titre de la page, sont contenu ou le contenu d'un commentaire.
    • masque.titre : filtre la liste sur le titre du texte
    • masque.txt : filtre la liste sur le texte. Ex. : "Ace mons"
  • txt.format (=text/plain|text/html) : indique le type de formatage du texte, en texte (=text/plain) par défaut ou avec des balises xhtml (=text/html).
  • txt.section : permet d'accéder au contenu d'une section de la page.
    • txt.section.position (=[0-9]+): retourne le texte correspondant au paragraphe (=section) correspondant à la position indiquée. Ex. : "txt.section.position=0"
    • txt.section.titre: retourne le texte correspondant au paragraphe (=section) correspondant au titre indiqué. Ex. : "txt.section.titre=Caractéristique"
  • recherche (=stricte|etendue) : type de recherche à lancer :
    • stricte : le masque est passé tel quel à l'opérateur LIKE. L'utilisateur a donc la possibilité d'utiliser le joker «%» pour remplacer n'importe quel nombre de caractères, y compris aucun et le «_» pour remplacer exactement un caractère.
    • etendue : ajout automatique du signe % à la place des espaces et en fin de masque avec utilisation de l'opérateur LIKE. Ex. : si le masque vaut "Ace mons", la recherche sera lancée sur "Ace%mons%".
  • retour (=json) : indique le type MIME des données à retourner.
    • json : correpond au type MIME application/json renvoyé par défaut.
  • navigation : permet en utilisant les sous-masques ci-dessous de naviguer dans les résultats.
    • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
    • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.

Création du fichier api.php
Dans le même dossier que wakka.php copier le fichier wakka.php en le renommant api.php.
Dans api.php à la dernière ligne du fichier supprimer: $wiki->Run($page, $method);

Modification du wiki existant
Pour adapter le wiki flora au nouveau format d'eflore il faut :
1/ renommer les pages des taxons (qui sont de la forme BDNFFntXXXXX) en BDTFXntXXXXX
2/ formater la page pour que leur contenu actuel passe dans la rubrique description
3/ vérifier que la page de template ' PageTaxon' qui permet de créer les pages vides structurées est présente
on peut trouver le format ici PageTaxon

Les requetes nécessaires peuvent être trouvées sur cette page [EfloreApi01WikiniRequetesMaj EfloreApi01WikiniRequetesMaj]]

TODO
  • API : Gérer les commentaires

Priorités de développement
  • /pages/#pageTag : GET, PUT, POST, DELETE
  • /pages/#pageTag/triples : GET, PUT, POST, DELETE
  • /triples : GET

  • /pages : GET
  • /pages/#pageTag/triples/#property(,#property1,#property2...) : GET, PUT, POST, DELETE
  • /pages/#pageTag/revisions
  • /pages/#pageTag/revisions/#timeRevision
  • /pages/#pageTag/acls
  • /pages/#pageTag/acls/read
  • /pages/#pageTag/acls/write
  • /pages/#pageTag/acls/comment
  • /pages/#pageTag/referrers
  • /pages/#pageTag/referrers/sites
  • /pages/#pageTag/backlinks
  • /pages/#pageTag/reseau
  • /referrers
  • /referrers/sites
  • /users
  • /users/#name
  • /triples/#ressource
  • /triples/#ressource/#property(,#property1,#property2...)

/pages
  • GET : retourne la liste des navigation.limite pages du wikini.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
 }


/pages/#pageTag
  • GET : retourne le contenu de la page #pageTag.
    • Paramètres :
      • retour (=text/plain,text/html) : indique le format des données à retourner.
        • text/plain : retourne le contenu de la page au format Wikini. Type mime correspondant : text/plain
        • text/html : retourne le contenu de la page transformé en HTML. Type mime correspondant : text/html
      • txt.template: indique que si la page n'existe pas, la page indiquée par ce paramètre doit être utilisée comme modèle pour la créer avant renvoyer le contenu
  • POST : récupère le contenu du paramètre POST "pageContenu" et modifier le contenu de la page, si le parametre pageSectionTitre est indiqué, et la section existe, modifie uniquement la section concernée
si la page n'existe pas, elle est crée (pour respecter le fonctionnement du wiki pour qui toute modification de page est une création de nouvelle page). Le remplacement de section par numéro n'est pas encore possible.
  • PUT : ajouter une nouvelle page avec le parametre POST pageTag et ajoute le contenu du paramètre POST "pageContenu".
  • DELETE : supprime la page #pageTag.

/pages/#pageTag/revisions
  • GET : retourne la liste des navigation.limite révisions de la page #pageTag.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
  • "resultats" : [ # Tableau des pages
    • "#timeRevision" : {# time de la révision
    • },...
  • ]
}


/pages/#pageTag/revisions/#timeRevision
Même fonctionnatilé que la ressource /pages/#pageTag. Si la ressource concerne une révision précise, dans la doc de /pages/#pageTag, #pageTag signifie la révision #timeRevision de la page #pageTag.

/pages/#pageTag/diff/#timeRevision1/#timeRevision2
- GET : retourne le diff de la page #pageTag entre la révision #timeRevision1 et #timeRevision2.
  • Paramètres :
    • retour (=wiki,html) : indique le format des données à retourner.
      • wiki : retourne le contenu de la page au format Wikini. Type mime correspondant : text/pain
      • html : retourne le contenu de la page transformé en HTML. Type mime correspondant : text/html

/pages/#pageTag/acls
  • GET : retourne la liste des droits de la page #pageTag.
    • Format de retour : (JSON)
{
  • "read" : "contenu du champ 'list' pour 'privilege=read' de la table 'acls' ",
  • "write" : "contenu du champ 'list' pour 'privilege=write' de la table 'acls' ",
  • "comment" : "contenu du champ 'list' pour 'privilege=comment' de la table 'acls' "
}

  • POST : modifie les droits de la page #pageTag. Les nouvelles valeur doivent être passées dans les paramètres POST 'read', 'write' et/ou 'comment'.
  • PUT : ajoute les droits de la page #pageTag. Les nouvelles valeur doivent être passées dans les paramètres POST 'read', 'write' et/ou 'comment'.
  • DELETE : supprime tous les droits de la page #pageTag.

/pages/#pageTag/acls/read
  • GET : retourne les droits de lecture de la page #pageTag.
    • Format de retour : (JSON)
{
  • "read" : "contenu du champ 'list' pour 'privilege=read' de la table 'acls' ",
}

  • POST : modifie les droits de lecture de la page #pageTag. La nouvelle valeur doit être passée dans le paramètre POST 'read'.
  • PUT : ajoute des droits de lecture à la page #pageTag. La valeur à ajouter doit être passée dans le paramètre POST 'read'.
  • DELETE : supprime les droits de lecture de la page #pageTag.

/pages/#pageTag/acls/write
  • GET : retourne les droits de lecture de la page #pageTag.
    • Format de retour : (JSON)
{
  • "write" : "contenu du champ 'list' pour 'privilege=write' de la table 'acls' ",
}

  • POST : modifie les droits d'écriture de la page #pageTag. La nouvelle valeur doit être passée dans le paramètre POST 'write'.
  • PUT : ajoute des droits d'écriture à la page #pageTag. La valeur à ajouter doit être passée dans le paramètre POST 'write'.
  • DELETE : supprime les droits d'écriture de la page #pageTag.

/pages/#pageTag/acls/comment
  • GET : retourne les droits de commentaire de la page #pageTag.
    • Format de retour : (JSON)
{
  • "comment" : "contenu du champ 'list' pour 'privilege=comment' de la table 'acls' ",
}

  • POST : modifie les droits de commentaire de la page #pageTag. La nouvelle valeur doit être passée dans le paramètre POST 'comment'.
  • PUT : ajoute des droits de commentaire à la page #pageTag. La valeur à ajouter doit être passée dans le paramètre POST 'comment'.
  • DELETE : supprime les droits de commentaire de la page #pageTag.

/pages/#pageTag/triples
  • GET : retourne la liste des triples dont le champ 'resource' de la table 'triples' vaut '#pageTag'.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
  • "resultats" : [ # Tableau des triples de la page #pageTag
    • "#property" : "#value",...
  • ]
}

  • POST : modifie les triples de la page #pageTag. Les nouvelles valeur doivent être passées dans les paramètres POST avec pour clés les valeurs du champ 'property'.
  • PUT : ajoute des triples à la page #pageTag. Les nouvelles valeur doivent être passées dans les paramètres POST avec pour clés les valeurs du champ 'property'.
  • DELETE : supprime tous les triples de la page #pageTag.

/pages/#pageTag/triples/#property(,#property1,#property2...)
  • GET : retourne la valeur du triple dont le champ 'resource' de la table 'triples' vaut '#pageTag' et le champ 'property' la valeur '#property'. Si plusieurs propriétés sont indiquées dans la ressource, le retour affichera les valeurs de ces différentes propriétés.
    • Format de retour : (JSON)
{
  • "#property" : "le contenu du champ 'value' pour la propriété '#property'",
  • "#property1" : "le contenu du champ 'value' pour la propriété '#property1'",...
}

  • POST : modifie le triple de la page #pageTag dont le champ 'property' a la valeur #property. La nouvelle valeur doit être passée dans les paramètres POST avec pour clé '#property'.
  • PUT : ajoute un triple à la page #pageTag dont le champ 'property' a la valeur #property. La nouvelle valeur doit être passée dans les paramètres POST avec pour clé la valeur '#property'.
  • DELETE : supprime le triple de la page #pageTag dont le champ 'property' vaut #property.

/pages/#pageTag/referrers
  • GET : retourne la liste des navigation.limite url ayant fait référence à la page #pageTag classées par nombre de références décroissantes.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
  • "resultats" : [ # Tableau des pages
    • "http://site.org/url/du/referrer" : {
      • "nbre" : "Nombre de fois où cette url est referrer de la page",
      • "dateDebut" : "Première date à laquelle l'url est référante",
      • "dateFin" : "Dernière date à laquelle l'url est référante",
    • },...
  • ]
}


/pages/#pageTag/referrers/sites
  • GET : retourne la liste des navigation.limite des domaines des urls ayant fait référence à la page #pageTag classées par nombre de références décroissantes.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
  • "resultats" : [ # Tableau des sites
    • "http://site.org" : {
      • "nbre" : "Nombre de fois où des urls de ce site font références à la page",
      • "dateDebut" : "Première date à laquelle le site possède une url faisant référence",
      • "dateFin" : "Dernière date à laquelle le site possède une url faisant référence",
    • },...
  • ]
}


/pages/#pageTag/backlinks
  • GET : retourne la liste des pages faisant référence à la page '#pageTag'.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
 }


/pages/#pageTag/reseau
  • GET : retourne le réseau de la page '#pageTag'.
    • Format de retour : (=svg)
      • svg : voir le handler svg correspondant
      • json : voir le handler svg correspondant pour identifier les données à extraire.

/referrers
  • GET : retourne la liste des navigation.limite URLs ayant fait référence à ce Wikini classées par nombre de références décroissantes.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
  • "resultats" : [ # Tableau des pages
    • "http://site.org/url/du/referrer" : {
      • "nbre" : "Nombre de fois où cette url est référante",
      • "dateDebut" : "Première date à laquelle l'url est référante",
      • "dateFin" : "Dernière date à laquelle l'url est référante",
    • },...
  • ]
}


/referrers/sites
  • GET : retourne la liste des navigation.limite des domaines des URLs ayant fait référence à ce Wikini classées par nombre de références décroissantes.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
  • "resultats" : [ # Tableau des sites
    • "http://site.org" : {
      • "nbre" : "Nombre de fois où des urls de ce site font références à ce Wikini",
      • "dateDebut" : "Première date à laquelle le site possède une url faisant référence",
      • "dateFin" : "Dernière date à laquelle le site possède une url faisant référence",
    • },...
  • ]
}


/users
  • GET : retourne la liste des navigation.limite utilisateurs du Wikini classées par date d'inscription décroissante.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
  • "resultats" : [ # Tableau des pages
    • "name" : {#contenu du champ 'name' de la table 'users'.
      • "href" : "http://mon-domaine.org/api/rest/users/#name",#lien vers le détail des infos de l'utilisateur
      • "motto" : "contenu du champ 'motto' de la table 'users'.",
      • "signuptime" : "contenu du champ 'signuptime' de la table 'users'."
    • },...
  • ]
}


/users/#name
  • GET : retourne les infos de l'utilisateur #name.
    • Format de retour : (JSON)
{
  • "name" : "contenu du champ 'name' de la table 'users'."
  • "password" : "voir si on le transmet (sécurité)",
  • "email" : "courriel de l'utilisateur. Voir aussi pb sécurité.",
  • "motto" : "contenu du champ 'motto' de la table 'users'.",
  • "revisioncount" : "contenu du champ 'revisioncount' de la table 'users'.",
  • "changescount" : "contenu du champ 'changescount' de la table 'users'.",
  • "doubleclickedit" : "contenu du champ 'doubleclickedit' de la table 'users'.",
  • "signuptime" : "contenu du champ 'signuptime' de la table 'users'.",
  • "show_comments" : "contenu du champ 'show_comments' de la table 'users'."
}


/triples
  • GET : retourne la liste des navigation.limite triples du Wikini classées par ordre alphabétique.
    • Paramètres :
      • navigation.depart : indique la ligne de résultat où débuter l'affichage des résultats. Par défaut vaut 0.
      • navigation.limite : indique le nombre de lignes de résultats à retourner. Par défaut vaut 100.
    • Format de retour : (JSON)
{
  • "entete" : {
    • "depart" : "0",
    • "limite" : "100",
    • "total" : "25"
    • # pas d'attributs 'href.precedent' et 'href.suivant' car tous les résultats sont affichés.
},
 }


/triples/#ressource
  • GET : retourne les propriétés de la ressource triple #ressource.
    • Format de retour : (JSON)
{
  • "contenu du champ 'property' de la table 'triple'." : "contenu du champ 'value' de la table 'triple'."
}

  • POST : modifie les triples de la ressource #ressource. Les nouvelles valeur doivent être passées dans les paramètres POST avec pour clés les valeurs du champ 'property'.
  • PUT : ajoute des triples à la ressource #ressource. Les nouvelles valeur doivent être passées dans les paramètres POST avec pour clés les valeurs du champ 'property'.
  • DELETE : supprime tous les triples de la ressource #ressource.

/triples/#ressource/#property(,#property1,#property2...)
  • GET : retourne la valeur de la propriété #property du triple #resource. Si plusieurs propriétés sont indiquées dans la ressource, le retour affichera les valeurs de ces différentes propriétés.
    • Format de retour : (JSON)
{
  • "#property" : "le contenu du champ 'value' pour la propriété '#property'",
  • "#property1" : "le contenu du champ 'value' pour la propriété '#property1'",...
}

  • POST : modifie la valeur de la propriété #property du triple #resource. La nouvelle valeur doit être passée dans les paramètres POST avec pour clé '#property'.
  • PUT : ajoute la valeur de la propriété #property du triple #resource. La nouvelle valeur doit être passée dans les paramètres POST avec pour clé '#property'.
  • DELETE : supprime la valeur de la propriété #property du triple #resource.