API Documentation


Examples - 13:20763071:T>C, 13:20763044, 13:20763045-20763071

API Calls

API Parameters and Their Inputs

Here is a table of all API Parameters and their accepted inputs excluding the Terms parameter due to its variability. The Terms (terms=) parameter is best examplified in the Common API Calls Breakdown section. Each parameter is listed with the url string usage in parentheses. An example of an API call would look like this: https://deafnessvariationdatabase.org/api?version=9&type=gvtable&method=download&format=csv&terms=GJB2

Version (version=)
9
Type (type=)
position
exactposition
hg19coord
gene
gvtable
dbinfo
Method (method=)
plain
download
exists
IO
Format (format=)
tab
csv
json
web
bool
Explanation of API Parameters
  • Version: Used to specify the DVD version to query for the API call.
  • Type: Used to specify the kind of data to be targetted with the API call.
  • Method: Used to specify how the data should be delivered to the requester.
  • Format: Used to specify the organization of the data returned by the API call.

API Call Return Format

API calls return a JSON object that may be different depending on the type of success or failure of an API call. In general, the returned JSON object is formed as follows:

Below is an explanation of common successful and unsuccessful calls to our API:

  • On Success with Data: The API Query was well-formed and returned data from the DVD. A JSON object is returned containing the status and a message of API Query success as well as a nested JSON object containing the search term and resulting data. Most often, the result data returned is a 'download_url', from which the DVD data may be viewed or downloaded from.
  • On Success with No Data: The API Query was well-formed but there was no relevant data to return from the DVD. A JSON object is returned containing the status and a message of API Query success as well as a nested JSON object containing the searchterm and a returned data field set to 'null'.
  • On Error: In this case, the DVD itself was not queried as the API could not interpret the request. A JSON object is returned containing the search term, a failed status (content set to "errors/format_error"), and a message indicating that the query was malformed and unrecognizable to the API. The JSON object would replace the successful 'messages' field with an 'error_messages' field that contains a list of strings.
    Examples of triggering events:
    • A Malformed API Query: This error would occur if the "api=" string contained invalid characters or invalid format for any of the API terms. The API returned JSON object's content would be set to "errors/format_error"
    • API Combination Not Available: This error would occur if the combination of valid API terms submitted were not supported at that time.

Break Down of Common API Calls

Version Type Method Format Example Terms API Call Assembled Description Raw Result
9 gvtable download csv GJB2 api?version=9&type=gvtable&method=download&format=csv&terms=GJB2 Initiates a download of a comma separated file containing all variants for the GJB2 gene in the DVD [A download of the csv formatted file is initiated]
json POU3F4 api?version=9&type=gvtable&method=download&format=json&terms=POU3F4 Initiates a download of a json file containing all variants for the POU3F4 gene in the DVD [A download of the JSON formatted file is initiated]
gene exists bool GATA3 api?version=9&type=gene&method=exists&format=bool&terms=GATA3 Check if variant information for GATA3 exists in the DVD. The JSON API return object's message field's content is set to "true" indicating that the gene GATA3 exists in the DVD.
position IO tab 13:20763044 api?version=9&type=position&method=IO&format=tab&terms=13:20763044 Gets variant data for variants that the position of 13:20763044. If variant data is found, the data will be written to a tab delimited file and a download url provided to the user. The download url will be nested into the content of the API Call JSON object at the field: 'download_url'. If no variant data is found at this position, the 'download_url' field will be set to 'null'.
hg19coord IO web 13:20763071:T>C, 13:20763044, 13:20763045-20763071 api?version=9&type=hg19coord&method=IO&format=web&terms=13:20763071:T>C, 13:20763044, 13:20763045-20763071 Searches the DVD for variant information for 3 indepdent search terms: a single variant - 13:20763071:T>C, variants at a position - 13:20763044, and variants within a range of positions - 13:20763045-20763071. Data should be returned in a webpage format [A search results webpage is returned similar to one that would be returned via the search bar]

Support

Please get in touch if you experience any issues with API access.