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

Description générale du fonctionnement de l'api eFlore v0.1

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://api.tela-botanica.org/service:eflore:0.1/#projet/#ressources
Cette URL sera composée :

"projet" (=code_projet) [obligatoire] : préciser le code du projet concerné par le service.
"ressources" : le nom de la ressource demandé (correspond au nom du fichier du service).

Cette URL pointera en réalité, dans un dossier :

/www/eflore/projets/services/#version_api/#code_projet/#nom_du_service.php

Méthodes et codes de retour

Par défaut, cette API sera accessible seulement en consultation. C'est donc la méthode HTTP GET qui sera utilisée pour y accéder.
Cette API devrait donc seulement retourner 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 nest 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.

Règles générales

Pour l'ensemble des ressources, le paramètre "retour.format" pourra être indiqué dans l'url. Il permettra de limiter les résultats aux seules informations disponibles dans la table sans recherche d'information complémentaire (valeur : min). Par exemple, pour un nom seuls les identifiants des noms liés seront fournis mais en aucun cas l'intitulé de ces noms.
Pour les champs comportant des codes (suffixe ".code"), ils auront le format : code_projet.code_valeur ou code_projet.code_categorie:code_valeur. Ex. : ISO-3166-1.fr ou eflore.GN:MS (interwiki inconnu). Les champs code servent à référencer des infos provenant de projets exterieurs au projet courant. Pour référencer des valeurs interne au projet, utiliser le suffixe ".id".
Pour chaque champ avec un code, une url vers la ressource fournissant des infos supplémentaires sera fournie. Le nom du champ sera suffixé par href. Ex. : basionyme.href
Pour chaque champ avec un code, le champ sans suffixe contiendra la valeur correspondant au code. Ex. :
- zone_geo = "France"
- zone_geo.code = "ISO-3166-1.fr"
- zone_geo.href = "api.tela-botanica.org/service:eflore:0.1/iso-3166-1/zones-geo/fr"
Les champs nommés "id", préfixé par "id_" ou suffixé par ".id" font référence à des valeurs internes au projet courant.
Si un champ ne contient pas de données, il ne sera pas affiché dans les résultats du service (cela évite de transférer des octets inutiles).
Si un champ peut contenir plusieurs données, utiliser un tableau d'objet comme valeur.
Pour le paramètre retour.champs :
- champ.id renvoie l'identifiant ou le code : "1/num_nom_retenu.id" => nom_retenu.id: "71574"
- champ.href renvoie l'url vers la ressource : "1/rang.href" => rang.href: http:/tela-botanica.org/service:eflore:0.1/bdnt/ontologie/rang.code:290
- champ.* renvoie tous les suffixes existant : "74979/nom_sci.*" => nom_sci.genre: "Asplenium" et nom_sci.epithete_sp: "fontanum"
- champ renvoie l'intitulé du code ou de l'id : "74979/rang" => rang: "espèce"
Principe pour passer plusieurs identifiant des les urls dans les paramètres ou les ressources :
- codeProjet1.codeId:#id1,#id2,#id3...;codeProjet2.codeId:#id1,#id2,#id3...;...
- Exemple : bdtfx.nt:1,2,3;bdtxa.nn:1,2,3

Types de service

Deux grands types de service existent :

recherche : service permettant de réaliser une recherche ou de naviguer dans les fiches
détail : service fournissant le détail d'une fiche

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.

Spécifiques au service de type recherche :

masque : filtre la liste en fonction d'un masque de recherche portant sur un libellé ou un nom.
masque.* : chaque ressource peut définir une série de sous masque de recherche spécifique.
recherche (=stricte|etendue|floue) : type de recherche à lancer (pour l'instant, uniquement sur le masque par défaut) :
- 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%".
- floue : recherche tolérante vis-à-vis d'approximations ou d'erreurs (fautes d'orthographe par exemple). Utilisation de SOUNDEX. Ex. : je tape "Acre", le service retournera "Acer" ou si je tape "Acer monspesulanum" le service retournera "Acer monspessulanum".
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.

Communs au deux types de service :

retour (=application/json|image/jpeg) : indique le type MIME des données à retourner.
- application/json (par défaut) : format JSON renvoyé par défaut.
- image/jpeg : format binaire JPEG image/jpeg
retour.format indique le format de retour.
- retour=application/json : (=max|min|oss|perso) :
  - max (par défaut) : un objet JSON contenant toutes les informations (même les intitulés des données liées).
  - min : pour obtenir seulement les infos de la table (les intitulés des infos liées doivent être obtenue via les href).
  - oss : format d'Open Search Suggest disponible uniquement pour les ressources Noms et Taxons.
  - perso : permet d'indiquer à l'aide du paramètre retour.champs les champs à retourner dans la réponse. Si le paramètre retour.champs est utilisé, la valeur pour retour.format sera automatiquement mise à perso.
- retour=image/jpeg (=predefini|largeur*hauteur|maximum)
  - predefini : image de taille défini : X3S à X3L
  - largeur*hauteur : largeur * hauteur en pixel : ex 800*600
  - maximum : nombre de pixels maximum en largeur ou hauteur en fonction de si l'image est en format portrait ou paysage : 800
retour.langue (=*|orig|code ISO-639-1.alpha-2) : indique la langue dans laquelle on veut récupérer les données de la ressource. Si les données ne sont pas disponibles dans la langue souhaitée, les données dans la langue par défaut seront malgré tout retournées.
- * : retourne l'ensemble des données dans les différentes langues disponibles.
- orig : renvoie les données dans la langue d'origine ou officielle. Utile pour les ressources ZonesGeo et Langues.
- code ISO-639-1.alpha-2 : indique le code ISO-3166-1.alpha-2 de la langue dans laquelle on souhaite recevoir les données. Par défaut, si la langue n'est pas indiquée, ce paramètre prendra la valeur ISO-3166-1.alpha-2 fr.
retour.champs (=champ1,champ2,...) : liste de noms de champs séparés par des virgules à faire figurer dans les résultats. Dans le cadre d'une recherche, indique les champs à ajouter. Dans le cadre d'un id, indique les champs à afficher.
version : permet d'indiquer avec les sous-masques ci-dessous une version précise de l'api ou du projet. Par défaut, les dernières versions sont utilisées.
- version.projet (=*|[code_version]|+) [optionnel] : indique si l'on veut les données pour un projet de toutes les versions (=*), d'une version précise (=[code_version]) ou de la version la plus récente (=+). Par défaut, les données de la version la plus récente sont renvoyées. Si aucune donnée n'est disponible, une erreur HTTP 404 sera retournée avec un contenu vide.
- version.api (=[code_version]|+) [optionnel] : numéro de version de l'API d'eFlore. Pour l'instant, prendra seulement la valeur : "0.1".