đź“Ž API Documentation

API documentation as generated by the code is:

http://data.agroportal.eu/documentation (exemples are not from AgroPortal)


API request examples

Vincent Emonet, Clement Jonquet - Septembre 2015

Administration via l'UI ou l'API, mais sans accès au serveur

Comment lire la documentation

Paramètres dans l'URL

Gestion des utilisateurs

  • Exemple de rĂ©cupĂ©ration d'un utilisateur

  • Exemple crĂ©ation d'un utilisateur

  • Exemple modification du rĂ´le d'un utilisateur

  • Exemple de suppression d'un utilisateur

Gestion des groupes et des catégories

  • Exemple de rĂ©cupĂ©ration d'une catĂ©gorie

  • Exemple de crĂ©ation d'une catĂ©gorie

  • Exemple de rĂ©cupĂ©ration d'un groupe

  • Exemple de crĂ©ation d'un groupe

  • Exemple de suppression d'une catĂ©gorie ou d'un groupe

  • Exemple d'ajout d'une ontologie dans un groupe et une catĂ©gorie

Gestion des ontologies et des soumissions

  • Exemple de rĂ©cupĂ©ration d'une ontologie

  • Exemple de rĂ©cupĂ©ration d'une soumission pour une ontologie

  • Exemple de rĂ©cupĂ©ration d'une classe d'une ontologie

  • Exemple de crĂ©ation d'une ontologie

  • Exemple de crĂ©ation d'une soumission

  • Exemple de suppression d'une ontologie

  • Exemple de modification d'une ontologie

  • Ontologie sans relation de subClassOf

  • Debugger une ontologie

  • Retirer la possibilitĂ© de download d'une ontologie

Gestion d'une ontologie privée

  • Exemple de crĂ©ation d'une ontologie privĂ©e visible

  • Restricting download of an ontology

Gestion des mappings

  • Exemple de rĂ©cupĂ©ration d'un mapping

  • Exemple d'ajout d'un mapping (minimum d'information)

  • Exemple d'ajout d'un mapping (maximum d'information)

  • Autres exemples de rĂ©cupĂ©ration des mappings

  • Exemple de suppression d'un mapping

  • Exemple de bulk load d'un fichier de mapping

Gestion des projets

  • Exemple de rĂ©cupĂ©ration d'un projet

  • Exemple de crĂ©ation d'un projet

Administration avancée (i.e., via accès au server)

Principaux projets de développement

Architecture du serveur

Emplacement des logs

DĂ©ployer des slices

  • Ajouter une slice

  • Supprimer une slice

  • Editer une slice

  • Mettre Ă  jour les slices en fonction des groupes

  • Paramètre REST pour s'adresser seulement Ă  une slice

Redémarrer le serveur

Commandes Linux utiles

DĂ©tails des sections

Comment lire la documentation

Exemple avec la documentation pour la manipulation de la ressource utilisateur: http://data.agroportal.lirmm.fr/documentation#User

La partie HTTP Methods for Resource présente les différentes opérations que l'on peut faire sur la ressource (dans ce cas les users) en donnant le verbe HTTP et le path URL à utiliser.

Par exemple pour obtenir les informations sur tous les users, faire un GET sur : http://data.agroportal.lirmm.fr/users

Mais pour obtenir les informations d'un seul user il faut remplacer la variable ":username" dans le path par le username du user dont on veut les informations : http://data.agroportal.lirmm.fr/users/jonquet

La partie Resource Description présente les différents attributs de la ressource. Cela permet de savoir quels attributs sont obligatoires (username et email pour user), quels attributs sont affichés par défaut, et lesquels sont présentés sous forme de liste (ici role, subscription et customOntology).

Paramètres dans l'URL

Quand vous parcourez le service REST dans votre navigateur il est possible d'avoir recours à des paramètres dans l'URL. Pour donner son apikey par exemple ou préciser que l'on veut un affichage détaillé de tous les attributs d'une ressource (tous les attributs ne sont pas affiché par défaut). Par exemple:

http://data.agroportal.lirmm.fr/users?apikey=72574b5d-b741-42a4-b449-4c1b64dda19a&display=all

Gestion des utilisateurs

Peut ĂŞtre fait manuellement par chaque utilisateur via l'interface graphique. Peut Ă©galement ĂŞtre fait via l'API REST.

Exemple de récupération d'un utilisateur

curl -X GET
-H "Authorization: apikey token=$APIKEY"
http://data.agroportal.lirmm.fr/users/jonquet

Exemple création d'un utilisateur

curl -X PUT
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{ "email": "$MYMAIL", "passwordHash": "$MYPASSWORD"}'
http://data.agroportal.lirmm.fr/users/$MYUSERNAME

Exemple modification du rĂ´le d'un utilisateur

curl -X PATCH
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{"role": ["LIBRARIAN"]}'
http://data.agroportal.lirmm.fr/users/jonquet

Exemple de suppression d'un utilisateur

curl -X DELETE
-H "Authorization: apikey token=$APIKEY"
http://data.agroportal.lirmm.fr/users/jonquet

A noter qu'il y a 2 types d'utilisateurs :

  • Les LIBRARIAN : utilisateur standard

  • Les ADMINISTRATOR : droits d'administrateur (droit de modification sur n'importe quelle ressource)

De plus, un utilisateur peut avoir des droits de gestion spécifique pour une ontologie. Il est alors administrateur de cette ontologie seulement.

Gestion des groupes et des catégories

La gestion des groupes et de catégories ne peut se faire que via l'API. L'affectation d'une catégorie à une ontologie peut se faire via l'interface graphique (au moment de la création de l'ontologie ou en l'éditant). Si une hiérarchie de catégorie existe, il faut explicitement ajouter toutes les catégories. Cependant l'affectation d'un groupe à une ontologie ne peut être fait que via l'API soit par un Administrator ou par l'administrateur de l'ontologie.

Exemple de récupération d'une catégorie

curl -X GET
http://data.agroportal.lirmm.fr/categories/CO_010-089

Exemple de création d'une catégorie

curl -X PUT
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{ "acronym": "CO_010-089",
"name": "010-089 General Germplasm",
"description": "This category includes ..."}'
http://data.agroportal.lirmm.fr/categories/CO_010-089

Exemple de récupération d'un groupe

curl -X GET
http://data.agroportal.lirmm.fr/groups/LOVINRA

Exemple de création d'un groupe

curl -X PUT
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{ "acronym": "LOVINRA",
"name": "INRA Linked Open Vocabularies",
"description": "Description please"}'
http://data.agroportal.lirmm.fr/groups/LOVINRA

Exemple de suppression d'une catégorie ou d'un groupe

curl -X DELETE
-H "Authorization: apikey token=$APIKEY"
http://data.agroportal.lirmm.fr/categories/EXEMPLE

curl -X DELETE
-H "Authorization: apikey token=$APIKEY"
http://data.agroportal.lirmm.fr/groups/EXEMPLE

Exemple d'ajout d'une ontologie dans un groupe et une catégorie

curl -X PATCH
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{"group": ["LOVINRA"], "hasDomain": ["Crop"]}'
http://data.agroportal.lirmm.fr/ontologies/CO_125

curl -X PATCH
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{"group": ["SEMANDIV"], "hasDomain": ["NATRES","TECH"]}'
http://data.agroportal.lirmm.fr/ontologies/ANAEETHES

Pour chaque ontologie du groupe, passer la commande précédente. Il est plus facile de passer par un script pour déclarer toutes les ontologies du groupe en une seule fois (voir les exemples de scripts).

Pour retirer une ontologie d'un groupe ou d'une catégorie il faut effectuer à nouveau un PATCH en mettant les nouveaux groupes ou catégories auquel l'ontologie appartient, cela écrasera la configuration précédente.

On peut voir les groupes disponibles avec : http://data.agroportal.lirmm.fr/groups

Gestion des ontologies et des soumissions

AgroPortal gère les versions d'ontologies de la façon suivante : Un objet ontology est créé pour chaque ontologie du portail. C'est un ensemble de métadonnées décrivant l'ontologie et qui ne change pas d'une version à l'autre (e.g., l'acronyme d'une ontologie qui sert d'identifiant local). Plusieurs soumissions (submission) peuvent être créées pour une ontologie donnée. C'est la soumission qui va contenir le véritable contenu de l'ontologie en plus de quelques autres métadonnées.

Exemple de récupération d'une ontologie

curl -X GET
http://data.agroportal.lirmm.fr/ontologies/CO_125

Exemple de récupération d'une soumission pour une ontologie

curl -X GET
http://data.agroportal.lirmm.fr/ontologies/CO_125/submissions/1

Exemple de récupération d'une classe d'une ontologie

curl -X GET
http://data.agroportal.lirmm.fr/ontologies/BIOREFINERY/classes/http%3A%2F%2Fopendata.inra.fr%2Fresources%2FBIORAF%23spruce

Exemple de création d'une ontologie

L'ajout d'une ontologie (ou d'une soumission) peut être réalisé via l'interface graphique: http://agroportal.lirmm.fr/ontologies/ > "Submit New Ontology"

Ou sur la page d'une ontologie sur l'onglet "Edit ontology information" ou "Edit submission information" pour les users qui ont le rôle Administrator ou les users qui sont administrateur de cette ontologie. Dans "Edit ontology information" et à la création de l'ontologie il est possible d'attribuer des "Administrators" à une ontologie.

L'administration d'ontologie offert par l'interface graphique est relativement complète. Donc, il est conseillé d'effectuer l'ajout et l'édition des ontologies ou soumissions via l'interface graphique. Hormis pour l'affectation à un groupe ou une catégorie (voir plus haut) qui ne peut être fait via l'UI.

Exemple de requĂŞte :

curl -X PUT
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{ "acronym": "MO",
"name": "Movie Ontology",
"administeredBy": ["jonquet"]}'
http://data.agroportal.lirmm.fr/ontologies/MO

Exemple de création d'une soumission

Ajout d'une nouvelle soumission Ă  une ontologie (nouvelle version de l'ontologie)

curl -X POST
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{ "contact": [{ "name": "Clément Jonquet",
"email": "jonquet@lirmm.fr"}],
"ontology": "http://data.agroportal.lirmm.fr/ontologies/MO",
"hasOntologyLanguage": "OWL",
"released": "2013-01-01T16:40:48-08:00",
"pullLocation":"http://www.movieontology.org/2010/01/movieontology.owl"}'
http://data.agroportal.lirmm.fr/ontologies/MO/submissions

Note : dans cet exemple seulement le strict minimum des informations requises a été donné. Pour plus d'informations sur les attributs de la ressource : http://data.agroportal.lirmm.fr/documentation#OntologySubmission

Exemple de suppression d'une ontologie

Suppression d'une ontologie (cela supprime automatiquement toutes les soumissions qui y sont rattachées)

curl -X DELETE
-H "Authorization: apikey token=$APIKEY"
http://data.agroportal.lirmm.fr/ontologies/MO

Exemple de modification d'une ontologie

Modification des métadonnées d'une ontologie. Ici on désigne "admin" et "jonquet" comme administrateurs de l'ontologie.

curl -X PATCH
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{ "adminstratedBy": ["admin", "jonquet"]}'
http://data.agroportal.lirmm.fr/ontologies/MO/

Exemple de modification d'une soumission

curl -X PATCH
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{ "homepage": "http://www.myhomepage.com",
"includedInDataCatalog":
["https://biosharing.org/bsg-s000139",
"http://aber-owl.net/ontology/PR",
"http://bioportal.bioontology.org/ontologies/PR",
"http://www.obofoundry.org/ontology/pr.html",
"http://www.ontobee.org/browser/index.php?o=pr",
"http://www.ebi.ac.uk/ols/ontologies/pr",
"http://vest.agrisemantics.org/content/protein-ontology"]
}'
http://data.agroportal.lirmm.fr/ontologies/XX/submissions/XX

Informations sur les propriétés du modèle de métadonnées: http://data.agroportal.lirmm.fr/submission_metadata

Ontologie sans relation de subClassOf

AgroPortal est également capable de prendre en charge des ontologies qui n'ont pas de relations de rdfs:subClassOf (l'absence de ses relations entraîne des problèmes quand le service essaie de mettre en place la hiérarchie, pour afficher l'arbre des concepts dans lUI par exemple). Pour cela il faut préciser via l'API REST que l'ontologie est "flat".

curl -X PATCH
-H "Content-Type: application/json"
-H "Authorization: apikey token=$APIKEY"
-d '{"flat": true}'
http://data.agroportal.lirmm.fr/ontologies/MO

Debugger une ontologie

Il se peut qu'une ontologie soulève des bugs quand elle est ajoutée

Il est possible d'avoir des informations sur les ontologies qui ont eu des problèmes lors de la soumission en se connectant sur un compte administrateur et en allant dans l'onglet "Admin". Cette interface permet de reset les caches du site et de voir les ontologies qui ont eu un problème à la soumission.

Il est ensuite possible de v