How to use the DISGENET plus REST API

Welcome to the REST API of DISGENET plus that enables the retrieval of information on genes and variants associated with human diseases.

How to query the REST API

To access the REST API of DISGENET plus, create your DISGENET plus account by filling the registration form. Once completed the registration process, you will be assigned an API key to authenticate your queries.
⇒ How to retrieve and use your API key: After completing the registration, you can login to the REST API portal of DISGENET plus. Your DISGENET plus user account page will show the following information:
  • API key: you need to use your API key in order to authenticate most of the REST API calls.
  • User profile: the type of your user profile (i.e. TRIAL or UNLIMITED).
In order to query the REST API of DISGENET plus, add to each API call an HTTP header with name equal to Authorization and value equal to your API key.

Endpoints

DISGENET plus REST API provides a set of endpoints to query information on genes and variants associated with human diseases. To get a detailed description of the input parameters and the format of the response of each REST API endpoint, access the REST API documentation. From the REST API documentation, by providing your API key, you can easily and interactively query all REST API endpoints as well as visually inspect the results.
⇒ Exploit your API key in the interactive REST API documentation:  the REST API documentation enables users to easily and interactively query all REST API endpoints as well as visually inspect the results. To this purpose, you need to provide your API key by accessing the REST API documentation and clicking the "Authorize" button (top-right corner, next to the green padlock symbol). A popup box named "Available authorizations" will open; copy your API key in the input box and click on the "Authorize" button. From now on all your API calls will be automatically authorized by means of your API key.
⇒ Response formats:  the results of the REST API queries can be retrieved in three different formats: JSON, XML and TSV (tabular, tab-separated). By default, the REST API provides the results in JSON format. To retrieve results in a different format, add to your API call an HTTP header with name equal to accept and value equal to: application/json, application/xml or application/csv.
⇒ Common response structure:  when using the JSON and XML response formats, all REST API endpoints have the following shared response fields:
  • status: the overall status of the API call execution (OK in case of correctly retrieved results).
  • error: in case of error, details on the type of error.
  • paging: when using pagination, total number of results retrieved by the query, current page number and number of results included in the current page.
  • warnings: a list of textual warning messages, if any.
  • requestpar: the API call parameters provided by the user.
  • userinfo: information concerning the user, including its profile.
  • payload: the actual results of the API call (the format depends on the specific API call invoked).
At the end of the REST API documentation, a detailed description of the fields of the REST API common response structure is available (see Response, ResponseError, Paging and UserInfo data models, in the Models section at the end of the REST API documentation).
The content of the payload field of each API call Response depends on the specific API endpoint invoked (i.e. /gda, /vda or /dda). In particular, at the end of the REST API documentation it is possible to access a detailed description of the fields of the payloads of each API endpoint (see GeneDiseaseAssocDTO, VariantDiseaseAssocDTO and DiseaseDiseaseAssocDTO data models, in the Models section at the end of the REST API documentation).
⇒ Pagination:  the endpoints of the REST API (i.e. /gda, /vda and /dda) support the pagination of search results. Given a specific configuration of query parameters, by relying on the pagination mechanism, it is possible to retrieve up to 10,000 search results (i.e. gene-disease, variant-disease or disease-disease associations). The number of search results present in each page is equal to 100. Pagination enables the access to the first 100 pages of search results (i.e. up to 10,000 search results): page numbers start from 0. The last page accessible is page number 99 (i.e. the 100th page).
⇒ Management endpoints:  the REST API provides two administration endpoints useful to retrieve and renew your API key (i.e. /public/retrievekey) and to obtain information on the current version of DISGENET plus data accessible by the REST API (i,e. /public/version, see the REST API documentation for more details).

Code examples

Below you can find Python and R code snippets showing how to programmatically interact with the REST API by means of YOUR_API_KEY.
⇒ Query the REST API with your API key:  the code below shows how to retrieve gene-disease associations related to the gene APP amyloid beta precursor protein with NCBI ID equal to 351 (gene_ncbi_id parameter equal to 351). To this purpose we call the gene-disease associations endpoint (i.e. gda endpoint, see the REST API documentation for more details). We retrieve the top-100 gene-disease associations involving such gene, ordered by descending gene-disease score, by asking for the first page of results (page_number parameter equal to 0).
import requests
import json

# Provide your API key 
API_KEY = "YOUR_API_KEY"

# Specify query parameters by means of a dictionary 
params = {}
# ...retrieve disease associated to gene with NCBI ID equal to 351 
params["gene_ncbi_id"] = "351"
# ...retrieve the first page of results (page number 0) 
params["page_number"] = "0"

# Create a dictionary with the HTTP headers of your API call 
HTTPheadersDict = {}
# Set the 'Authorization' HTTP header equal to API_KEY (your API key) 
HTTPheadersDict['Authorization'] = API_KEY
# Set the 'accept' HTTP header to specify the response format: one of 'application/json', 'application/xml', 'application/csv' 
HTTPheadersDict['accept'] = 'application/json'

# Query the gda endpoint 
response = requests.get("https://api.disgenetplus.com/api/v1/gda",\
                        params=params, headers=HTTPheadersDict, verify=False)

# Parse response content in JSON format since we set 'accept:application/json' as HTTP header 
response_parsed = json.loads(response.text)
print('STATUS: {}'.format(response_parsed["status"]))
print('TOTAL NUMBER OF RESULTS: {}'.format(response_parsed["paging"]["totalElements"]))
print('NUMBER OF RESULTSRETRIEVED BY CURRENT CALL (PAGE NUMBER {}): {}'.format(\
      response_parsed["paging"]["currentPageNumber"], response_parsed["paging"]["totalElementsInPage"]))
library(httr)
library(jsonlite)

# Provide your API key 
api_key <- "YOUR_API_KEY"

# Specify the response format: one of 'application/json', 'application/xml', 'application/csv' 
resp_format <- "application/json"

# Query the gda endpoint by specifying the following parameters:
# - gene_ncbi_id=351: retrieve disease associated to gene with NCBI ID equal to 351
# - page_number=0: retrieve the first page of results (page number 0)
# and providing your API key (api_key) and the response format (resp_format) as HTTP headers
res <- GET("https://api.disgenetplus.com/api/v1/gda?gene_ncbi_id=351&page_number=0",
           add_headers(.headers = c('Authorization'= api_key,
                                    'accept' = resp_format)))

# Extract the content type of the response and parse the JSON content since we set 'accept:application/json' as HTTP header 
http_type(res)
query_result <- fromJSON(rawToChar(res$content))
    		  


User profile types

Currently, the REST API of DISGENET plus includes two types of user profiles:
  • TRIAL: characterized by limited access to DISGENET plus data. The data access limit of a TRIAL account are specific to each REST API endpoint and are documented by means of the endpoint descriptions of the REST API documentation.
  • UNLIMITED: characterized by unlimited access to DISGENET plus data.


Information and support

For any issue concerning the REST API of DISGENET plus, please contact info@disgenetplus.com.