DISNET API DOCUMENTATION
Getting Started
Base URL
disnet.ctb.upm.es/api/disnet
Schemes
HTTP | HTTPS
Requirements
The requirement to use this API is to have a DISNET account. When an account is generated, an access token (unique identifier) is provided. The token must always be included in every request made to a service, if it is active the service will respond to the request made, otherwise the results will not be displayed.
The token is obtained by signing up in the DISNET Web application, which can be found here.
Quick Start
Overview of API usage.
- Select tool. To visualize the results of the requests there are two ways to do it: 1) with a Web viewer, use the one of your preference (Opera, Chrome, Firefox, Safari, IE, among others) and 2) some program that allows to consume Web services, we recommend the use of Postman available for users Windows, Mac OS X, Linux and Chrome in its official Web page https://www.getpostman.com.
- Select service of your interest from DISNET's list of official services.
- Make a query by setting the requested search parameters according to each service.
- Send the formed query.
- Visualize the query response.
REST API Introduction
Currently the DISNET API has eleven queries, in Service List section we can see the detailed list of services offered by DISNET with a short description of its function.
In our system, we call "DISNET Concept" to all those terms we store that are validated positively (symptoms) as the medical concepts that were validated negatively and that therefore are not symptoms or signs. All our queries that respond with a list of DISNET Concepts by default return the validated ones positively, but also allow to return the validated ones negatively.
These queries are made with a view to providing as much relevant data as possible to users, so they can be consulted from the sources of knowledge that have been mined, the snapshots that have been made, the list of all diseases from a source and a snapshot, to the configurations by which a particular snapshot has been created.
You can also look at some predefined queries here in a Postman collection file.
NLP Tools and Configuration
Metamap1 was developed by the National Library of Medicine (NLM) and is one of the most widely accepted applications of NLP in biomedicine. When Metamap analyzes texts and identifies words or phrases, it relates and assigns them to concepts of NLM's Unified Medical Language System (UMLS), so we have terms that can be used by other biomedical applications that use the unique identifier concept (CUI) of UMLS (Aronson, 2001; Park et al., 2015).
In our research work we processed the texts of our database with Metamap version 2016v2.
To add Metamap to the DISNET system we have developed a Web service that consumes Metamap by means of a request that contains the indications of its configuration. Next, we will describe the part of the request that is related to the Metamap configuration.
The standard configuration we use with Metamap first includes a list of semantic types of concepts to be detected from a much larger list provided by this tool2. Our own configuration is shown in Fig. 1. The semantic types we use are 6: Diagnostic Procedure (diap), Disease or Syndrome (dsyn), Finding (fndg), Laboratory Procedure (lbpr), Laboratory or Test Result (lbtr) and Sign or Symptom (sosy). If we only focus on detecting sosy concepts, the scope of discovering phenotypic manifestations for a disease would be very limited. Extending the filter over the texts, telling Metamap to look for other types of concepts allows you to retrieve more diagnostic concepts.
Let's look at an example of the filtering Metamap does with our configuration, taking a piece of text obtained from the Signs and symptoms section of the Wikipedia article about the Brain Salt-wasting Syndrome3 extracted on February 1st, 2018: “Advanced symptoms[sosy] include muscle cramps[sosy], lightheadedness[sosy], dizziness[sosy] or vertigo[sosy], feelings of anxiety or panic[fndg] (not mentally induced), increased heart rate or slowed heart rate, low blood pressure[fndg] and orthostatic hypotension[fndg] sometimes resulting in fainting[sosy]”. The words or phrases that Metamap has detected, along with their semantic types, are indicated in bold letters. We clearly observe that there are four words that were detected with the semantic type fndg, which are phenotypical manifestations of the syndrome and if we had not indicated that semantic type we would lose consciousness.
The next configuration element is source, which lists the subset of source vocabularies in which we want Metamap to search, first of all we use SNOMEDCT_US and DSM-54.
Another essential configuration element is, options, which determine which options to activate for filtering, for example, when we indicate "-y" we are telling Metamap to activate word disambiguation. And when we write "-R" we saying Metamap to use the vocabulary list that we have previously indicated. To see all Metamap options you can visit the following link5.
Fig. 1. Standard options and settings for Metamap
Finally, we find the concept_location option that allows us to indicate Metamap to return extra information about the location of each concept found. This information includes the word or words by which the NLP tool found some concept and its position within the text. In this link, in the "Performing" section to query using the API we find information about everything we can get from Metamap through its Java development API.
We do not rule out using any other NLP tool, in the analysis of the related work we mention some of them that can help us to obtain better results.
Service List
Query path | Short description | |
---|---|---|
1 | /query/sources | Retrieve sources list |
2 | /query/snapshots | Retrieve all available snapshots for a given source |
3 | /query/disnet-diseases | Retrieve diseases list for a given source and snapshot |
4 | /query/disnet-diseases?name={name} | Retrieve DISNET Concept list for a given source and snapshot. Search by disease: exact name or not, other vocabulary code, excluding or forcing semantic types |
5 | /pheno/disnet-diseases/{disnet-id}/url | Retrieve number of diseases for a given source and snapshot |
6 | /pheno/disnet-diseases/{disnet-id}/symptoms | Retrieve disease(s) with more DISNET Concepts for a given source and snapshot |
7 | /pheno/symptoms | Retrieve disease(s) with fewer DISNET Concepts for a given source and snapshot |
8 | /pheno/symptoms?name={name} | Retrieve most common DISNET Concepts for a given source and snapshot |
9 | /pheno/symptoms/{cui}/diseases | Retrieve less common DISNET Concepts for a given source and snapshot |
10 | /pheno/metadata | Retrieve disease(s) for a given source and snapshot by exact name or not |
Description of Services
The following is a detailed description of each of the Web services that make up the DISNET API.
Retrieve sources list
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve all available snapshots
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve diseases list
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve DISNET Concept list for a given disease
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve number of diseases
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve disease(s) with more DISNET Concepts
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve disease(s) with fewer DISNET Concepts
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve most common DISNET Concepts
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve less common DISNET Concepts
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve disease(s) by name
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Retrieve metadata for a given snapshot
Information will added soon
-
Description
...
-
URL (PATH)
/query/sourceList?
-
Method
GET
-
Auth required
Yes (token)
-
Request parameters description
Parameter Description token *required
[alphanumeric]
example: token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJncmGlGG...Access key that allows the query to be executed. -
Example request
...
-
Success response (application/json)
...
Example:
...
-
Error response (application/json)
...
Example:
...
Common errors
Information will added soon