API Calls
API Parameters and Their Inputs
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 if you experience any issues with API access.