HeTOP Web Service

SOAP and REST web service protocols for programmatic use

HeTOP basics

Check at the developer's guide for details about how HeTOP works. It is highly recommended if you want to play with the HeTOP web service.

Web services

Check at this tutorial if you are a beginner with web services.

Web service call

This section is dedicated to developers! The HeTOP web service is available with the REST and SOAP protocols but authentication is required. You can use the web site identifiers or create a new one here.

REST

Check at the WADL here. The REST protocol is adapted to web technologies so it is very simple to use even in a web browser. Nevertheless, as authentication is required, you have to use a dedicated tool such as the RESTClient plugin for Mozilla Firefox or the Insomnia REST Client for Google Chrome. Try this URI with one of these plugins or in a dedicated client:

https://www.hetop.eu/CISMeFhetopservice/REST/searchConcepts/asthma/en/*

REST authentication

You need to use the HTTP Basic Authentication in order to use HeTOP web service with REST (protocol RFC-7235). To make it simple, if you are building your own client programmatically, you'll have to proceed this way:

  1. Build a string of the form username:password
  2. Base64 encode the string
  3. Supply an "Authorization" header with content "Basic " followed by the encoded string

For example, the string "fred:fred" encodes to "ZnJlZDpmcmVk" in base64, so you would make the request with the following header inclusion: "Authorization: Basic ZnJlZDpmcmVk" (check at this full tutorial).

SOAP

Check at the WSDL here. The SOAP protocol is the standard of web services. It is not very convenient by it is a standard and it works fine as well!

Options

The two methods search(query, langs, options) and getByIds(cismefIds, langs, options) of this web service accept additional options in order to:

  • Lower response times (skip some steps)
  • Make the XML output lighter
  • Ignore non relevant categories

The "options" argument is a string that looks like URL parameters, i.e. a=true&d=false&sn=true&rw=true&at=true (the order of the parameters does not matter).

Check at the available options:

Argument Stands for Type Description
c categorization boolean If set to true, it will return metaterms (super-concepts) and UMLS semantic types related to the found concepts. Default value is true.
sn semantic network boolean If set to true, mapped concepts with found concepts will also be returned. The mapping relationships used are "CISMeF supervised automatic exact mappings" and "CISMeF manual mappings". Default value is true.
e exclusions concepts ids or concept types Given concepts ids or concept types are excluded from the response. Example: e=CIS_MT_8,UML_ST_T060,MSH_D_C,T_DESC_PHARMA_RACINE will not return concepts linked to surgery (concept id CIS_MT_8), to Diagnostic Procedure (concept id UML_ST_T060), descendants from diseases (concept id MSH_D_C) and all Pharmaceutical roots (concept type T_DESC_PHARMA_RACINE). Default value is empty.
f filters concept types Only given concept types are returned among found concepts. Example: f=T_DESC_MESH_DESCRIPTEUR,T_DESC_SNOMED_NOTION will only return MeSH descriptors (T_DESC_MESH_DESCRIPTEUR) and SNOMED int. notions (T_DESC_SNOMED_NOTION). Default value is empty.
a ancestors boolean If set to true, it will return ancestors (from hierarchies: parents, grandparents, etc.) of found concepts. Default value is true.
d descendants boolean If set to true, it will return descendants (from hierarchies: children, grandchildren, etc.) of found concepts. Default value is false.
at alternative terms boolean If set to true, alternative terms (~synonyms) of found concepts are returned. Default value is true.

The search(query, langs, options) method provides two additional parameters:

Argument Stands for Type Description
rw right wildcard boolean If set to true, it will use a right wildcard to search terms starting with the user query. Example: query asthm (which equals for asthm*) will return asthma. Default value is true.
lw left wildcard boolean If set to true, it will use a left wildcard to search terms ending with the user query. Example: query sthma (which equals for *sthma) will return asthma. Default value is true.

Response

The HeTOP web service returns an XML file based on a proprietary format. Here is a brief description of all encountered tags:

Tag Description
cis:dboResp Concept list
cis:dbo Concept
cis:id Concept identifier
cis:ti Metadata identifier (concept, data property or relation property)
cis:lb Concept or metadata label
cis:an Concept or metadata annotation
cis:dps Data property list
cis:dp Data property
cis:hies Hierarchy list
cis:hie Hierarchy
cis:bt Broader concept
cis:nt Narrower concept
cis:path Hierarchy path
cis:ops Relation list
cis:op Relation between concepts
cis:tar Target concept id