# 📎 API Documentation API documentation as generated by the code is: [http://data.agroportal.eu/documentation](http://data.agroportal.lirmm.fr/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: 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 : 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 : 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: ### 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 ```bash curl -X GET -H "Authorization: apikey token=$APIKEY" http://data.agroportal.lirmm.fr/users/jonquet ``` #### Exemple création d'un utilisateur ```bash 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 ```bash 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 ```bash 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 ```bash curl -X GET http://data.agroportal.lirmm.fr/categories/CO_010-089 ``` #### Exemple de création d'une catégorie ```bash 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 ```bash curl -X GET http://data.agroportal.lirmm.fr/groups/LOVINRA ``` #### Exemple de création d'un groupe ```bash 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 ```bash 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 ```bash 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 : ### 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 ```bash curl -X GET http://data.agroportal.lirmm.fr/ontologies/CO_125 ``` #### Exemple de récupération d'une soumission pour une ontologie ```bash curl -X GET http://data.agroportal.lirmm.fr/ontologies/CO_125/submissions/1 ``` #### Exemple de récupération d'une classe d'une ontologie ```bash 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: > "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 : ```bash 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) ```bash 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 : #### Exemple de suppression d'une ontologie Suppression d'une ontologie (cela supprime automatiquement toutes les soumissions qui y sont rattachées) ```bash 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. ```bash 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 ```bash 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: #### 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". ```bash 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 --- **Documents** - [💁‍♂️ Acknowledgments](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/acknowledgments-15GdRXLQdm) - [📚Publications and references](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/publications-and-references-87tEoeoGKy) - [🗽Terms & Conditions](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/terms-conditions-naDsDo2Zxq) - [🧞‍♂️Metadata guidelines and recommendations](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/metadata-guidelines-and-recommendations-pOFbK9sIfp) - [📜 AgroPortal Release Notes](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/agroportal-release-notes-btKjZk5tU2) - [ 👩‍🚀 User Guide](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/user-guide-ZszoBwfjGF) - [📎 API Documentation](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/api-documentation-kMCurGKD97) - [🤖 Developer Documentation](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/developer-documentation-LhsrucqGTa) - [🗃External Documentation](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/external-documentation-vNPQCdArrr) - [AgroPortal infrastructure](https://wiki.agroportal.eu/s/e6158eda-c109-4385-852c-51a42de9a412/doc/agroportal-infrastructure-ietsAU4kPs)