SOAP and REST web service protocols for programmatic use
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.
Check at this tutorial if you are a beginner with web services.
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.
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/*
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:
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).
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!
The two methods search(query, langs, options) and getByIds(cismefIds, langs, options) of this web service accept additional options in order to:
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. |
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 |