API

In this database, the REST API uses HTTP queries to retrieve all meaningful biological information. Queries to most of the endpoints can be refined by adding filters, which are often shared among many endpoints - it makes the system easier to learn and use, as the same syntax is always valid across different endpoints. In case of any problems see troubleshooting section at the end of this document.

The output is in JSON format.

 

Protein-specific endpoints

By default, you will get results for all mutations sets. For instructions to specify only one or subset of dataset, please refer to filters section.

An empty response (404 or '[]')  or a verbose warning (see below) indicates that there are no mutations in the chosen dataset.

 

Single mutation

Get a single, point mutation.

Both known (already annotated and accessible in one of our datasets) and novel mutations are returned by this endpoint until a dataset filter is specified.

If there is no mutation matching the given filters, a warning: Warning: There is a mutation, but it does not satisfy given filters is returned.

 

Attributes:

Attribute Example value
refseq NM_000123
mutation_position 77
mutated_residue (alternative) amino acid L

Syntax:

/protein/mutation/{refseq}/{mutation_position}/{mutated_residue}


Examples:

A novel mutation in TP53, isoform NM_000546:
activedriverdb.org/protein/mutation/NM_000546/76/L

A known mutation in TP53 (it belongs to MC3/TCGA mutations dataset):
activedriverdb.org/protein/mutation/NM_000546/77/L

TP53 R282W is a known mutation in TP53. It belongs to three mutation datasets: MC3/TCGA, ClinVar and ESP6500.

all data about TP53 R282W:
https://activedriverdb.org/protein/mutation/NM_000546/282/W

only data from ESP6500:
https://activedriverdb.org/protein/mutation/NM_000546/282/W?filters=Mutation.sources:in:ESP6500

try to get data for The 1000 Genomes Project:
https://activedriverdb.org/protein/mutation/NM_000546/282/W?filters=Mutation.sources:in:1KGenomes

In the last case, the server issues warning: such a mutation is possible but it does not match specified criteria.
It is because this mutation was not detected in The 1000 Genomes Project study.


All known mutations in given isoform sequence

Return all mutations from given isoform which belong to any of our datasets. Mutations returned by this endpoint are known that is they are in one of ours datasets.

 

Attributes:

Attribute Example value
refseq NM_000123

Syntax:

/protein/known_mutations/{refseq}


Example:

activedriverdb.org/protein/known_mutations/NM_000123

Get all mutations in gene `NM_000123` and from dataset ESP6500:
activedriverdb.org/protein/known_mutations/NM_000123?filters=Mutation.sources:in:ESP6500

 

 

Network endpoint

Network representation is provided as "network" attribute of an object returned by endpoint with following attributes:

Attributes:

Attribute Example value
refseq NM_000123

Syntax:

/network/representation/{refseq}

 Example:

activedriverdb.org/network/representation/NM_007300

 

Genomic endpoints

All genomic coordinates are 1-based. Stop codon and silent mutations are not considered.

 

Single DNA mutation

This endpoint allows you to convert genomic position to resultant protein mutation and retrieve all information about this mutation. If the mutation does not map to a known coding sequence, an empty response will be returned.

Please note that this endpoint is strand sensitive - if your gene of interest is placed on reverse strand (as defined in hg19/GRCh37) you need to provide nucleotides as on reverse strand (e.g. reference should be complementary to the forward strand).

Attributes:

Attribute Example
chromosome chr1
position 123456
major_allele A
minor_allele T

Syntax:

/chromosome/mutation/{chromosome}/{position}/{major_allele}/{minor_allele}


Example:

activedriverdb.org/chromosome/mutation/chr12/57490358/G/T

 

Filters

You can specify one or more filters by appending 'filters' query string to any of endpoints. Remember to start from a question mark and add equality sign after word 'filters'. It should look like:

/{chosen_endpoint}/{some_argument}?filters={your_filters}

 

A single filter


You should specify three things for each filter:

1. A target (an accessor; which property from which model should be taken into account)
2. A comparator (how the value of given target should be compared to the value that you will specify)
3. A value (which values of target you want to include/exclude, use to compare)

The three elements are separated by colons, so a single filter should be like:

/endpoint/arg?filters=Mutation.sources:in:1KGenomes


Multiple filters

Combining filters means that both filters should be satisfied for given entity ("and" joining).

To combine filters, separate them with semicolons:

/endpoint/arg?filters=Mutation.sources:in:1KGenomes;Mutation.populations_1KG:in:African

 

Multiple values

You can add more than one value (separated by commas) if it is sensible for given comparator. For example, you can write:

/endpoint/arg?filters=Mutation.sources:in:1KGenomes;Mutation.populations_1KG:in:East Asian,African

 

Comparators

There is a number of comparators available. Often filters restrict the use of comparators to specified subset which is called "allowed comparators". It is often the case for values or targets that are list-based - then only operators like 'in' or 'ni' are sensible.

Following comparators might be used:

Comparator Meaning
ge is x greater or equal to y?
le is x lower or equal to y?
gt is x greater than y?
lt is x lower than y?
eq is x equal to y?
in does x contain y?
ni does y contain x?
 

Troubleshooting


If you get the following message:

This site can’t be reached
activedriverdb.org refused to connect.

check if your URL starts with https://, not http://.