Les bases de HeTOP

Jetez un oeil au guide du développeur pour en savoir plus sur le fonctionnement de HeTOP. C'est fortement recommandé si vous voulez jouer avec le service web de HeTOP.

Services Web

Suivez ce tutoriel si vous débutez en services web.

Appel au service web

Cette section est dédiée aux développeurs! Le service web de HeTOP est disponibles pour les protocoles REST et SOAP mais une authentification est requise. Vous pouvez utiliser les mêmes identifiants que ceux du site web ou en créer un ici.

REST

Consultez le WADL ici. Le protocole REST est adapté aux technologies du web et est donc très simple d'utilisation y compris via un navigateur web. Cependant, comme une authentification est requise, vous devez utiliser un outil dédié comme le plugin RESTClient de Mozilla Firefox ou le Client Insomnia REST pour Google Chrome. Essayez cette URI avec l'un de ces plugins dans votre navigateur web :

https://www.hetop.eu/CISMeFhetopservice/REST/searchConcepts/asthme/fr/*

Authentification REST

Vous devez utiliser l'authentification "HTTP Basic" pour utiliser le service web de HeTOP en REST (protocole RFC-7235). Pour faire simple, si vous créer votre propre client programmatiquement, vous devrez vous y prendre ainsi:

1. Construire une chaîne de caractères de la forme username:password
2. Encoder en base64 cette chaîne
3. Renseigner le champ "Authorization" dans l'entête (header) de la requête avec "Basic " suivi par la chaîne encodée

Par exemple, la chaîne "fred:fred" est encodée en "ZnJlZDpmcmVk" en base64, et vous pourrez alors rajouter le champ suivant dans l'entête de la requête HTTP : "Authorization: Basic ZnJlZDpmcmVk" (voir le tutoriel complet).

SOAP

Consultez le WSDL ici. Le protocole SOAP est le standard des services web. Il n'est pas très pratique à utiliser mais c'est un standard et ça marche bien!

Options

Les deux méthodes search(query, langs, options) et getByIds(cismefIds, langs, options) de ce service web acceptent un paramètre particulier qui permet de :

• Améliorer les performances (certaines étapes peuvent être ignorées)
• Alléger le XML résultant
• Ignorer des métadonnées non pertinentes

L'argument "options" est une chaîne de caractères construite comme des paramètres d'URL, exemple : a=true&d=false&sn=true&rw=true&at=true (l'ordre des paramètres importe peu).

Voici les options disponibles :

Argument	Forme développée	Type	Description
c	categorization (catégorisation)	booléen	À true, cela retournera les métatermes (super-concepts) et les Types Sémantiques de l'UMLS des concepts trouvés. La valeur par défaut est true.
sn	semantic network (réseau sémantique)	booléen	À true, les concepts alignés (exactement) aux concepts trouvés seront également retournés. Les relations d'alignements concernées sont les "Alignements exacts supervisés CISMeF" et les "Alignements manuels CISMeF". La valeur par défaut est true.
e	exclusions	identifiants de concepts ou types de concepts	Les identifiants donnés seront exclus de la réponse. Exemple : e=CIS_MT_8,UML_ST_T060,MSH_D_C,T_DESC_PHARMA_RACINE ne retournera pas les concepts liés à chirurgie (concept d'id CIS_MT_8), à procédure de diagnostic (concept d'id UML_ST_T060), les descendants de maladies (concept d'id MSH_D_C) et toutes les Racines Pharmaceutiques (type de concepts T_DESC_PHARMA_RACINE). La valeur par défaut est vide.
f	filters (filtres)	types de concepts	Seuls les concepts appartenant aux types spécifiés seront retournés. Exemple : f=T_DESC_MESH_DESCRIPTEUR,T_DESC_SNOMED_NOTION ne retournera que les descripteurs MeSH (T_DESC_MESH_DESCRIPTEUR) et les notions SNOMED int. (T_DESC_SNOMED_NOTION). La valeur par défaut est vide.
a	ancestors (ancêtres)	booléen	À true, cela retournera les ancêtres (à partir de leur hiérarchies : parents, grand-parents, etc.) des concepts trouvés. La valeur par défaut est true.
d	descendants	booléen	À true, cela retournera les descendants (à partir de leur hiérarchies : enfants, petits-enfants, etc.) des concepts trouvés. La valeur par défaut est false.
at	alternative terms (termes alternatifs)	booléen	À true, les termes alternatifs (~synonymes) des concepts trouvés seront également retournés. La valeur par défaut est true.

La méthode search(query, langs, options) fournit deux paramètres additionnels :

Argument	Forme développée	Type	Description
rw	right wildcard (joker à droite)	booléen	À true, cela ajoutera automatiquement un caractère de joker de recherche à la fin de chaque mot de la requête (*). Exemple : la requête asthm donnera asthm* et retournera asthme. La valeur par défaut est true.
lw	left wildcard (joker à gauche)	booléen	À true, cela ajoutera automatiquement un caractère de joker de recherche au début de chaque mot de la requête (*). Exemple : la requête sthma donnera *sthma et retournera asthme. La valeur par défaut est true.

Réponse

Le service web de HeTOP retourne un fichier XML basé sur un format propriétaire. Voici une description succinte des balises rencontrées :

Balise	Description
cis:dboResp	Liste de concepts
cis:dbo	Concept
cis:id	Identifiant de concept
cis:ti	Identifiant de métadonnée (concept, propriété ou relation)
cis:lb	Libellé de concept ou de métadonnée
cis:an	Annotation de concept ou de métadonnée
cis:dps	Liste d'attributs (data property)
cis:dp	Attribut (data property)
cis:hies	Liste de relations hiérarchiques
cis:hie	Relation hiérarchique
cis:bt	Concept "large" (broader)
cis:nt	Concept "étroit" (narrower)
cis:path	Chemin hiérarchique
cis:ops	Liste de relations
cis:op	Relation (entre concepts)
cis:tar	Identifiant de concept cible