RESTful Web Services API

To make this entire database accessible to researchers, a RESTful Web Service API has been implemented. This API contains several methods designed to facilitate researchers query and obtain regulatory information from a single database saving a lot of time.

Understanding RESTful WS API

General structure of the implemented RESTful call is:<version>/<species>/<category>/<subcategory>/id/<resource>?filters

Sections in braquets are parameters, so they are variable entities:


As is explained in this documentation, this REST call will get all transcription factor binding sites (TFBSs) related to the gene BRCA2 in human.

Note: All sections in URL must be in lower case!

versionVersions are numbered as v1, v2, v3, etc consecutively. At this moment the public version is v1. Use latest to use the most updated version.
speciesCurrently, the supported species are human and mouse. Both, the abbreviated form (i.e: hsapiens, mmusculus) and the 3-letter code (i.e: hsa, mmu) are accepted.
categoryThere are 3 main categories (regulatory, genomic and feature) that permit the access according to the nature of your query identifier (id).
subcategorySubcategories should specify the type of the id field. Subcategories can be different for each category and are described within each of the categories mentioned above.
idIt is the query parameter, the feature or term about we want to retrieve the information. Its type must correspond with the subcategory. In order to improve performance, ID lists can be passed together in only one REST call separated by commas.
resourceEach Category and Subcategory can have different resources and actions allowed. They specify the type of result we want to obtain from the id.
filtersWe can add filters or extra-options to the REST query. Some of them can be applied to all queries, but some of them are specific of each subcategory.

Categories and subcategories

Regulatory category

Regulatory category refers to regulatory elements, such transcription factors and microRNAs.

URL pattern:<version>/<species>/regulatory/<subcategory>/id/<resource>


URL pattern:<version>/<species>/regulatory/tf/tf1, tf2/<resource|action>
Format: HGNC Symbol, Ensembl gene, Ensembl TF Name.
Resources or actions:

URL pattern:<version>/<species>/regulatory/mirna_mature/mirna_mature1, mirna_mature2/<resource>
Format: miRBase name/identifier.
Resources or actions:

URL pattern:<version>/<species>/regulatory/mirna_gene/mirna_gene1, mirna_gene2/<resource|action>
Format: miRBase name/identifier.
Resources or actions:

Genomic category

Genomic category makes reference to the coordinates necessary to place a position or a region in the genome. Using these coordinates, the user can query our database to retrieve any regulatory information within a position or region.

URL pattern:<version>/<species>/genomic/<subcategory>/id/<resource|action>


  • region:
    URL pattern:<version>/<species>/genomic/region/region1, region2/<resource|action>
    Chr. region format: chr:start-end (i.e.: 7:245000-501560). Use the same start and end to indicate a position.
    Resources or actions:

Feature category

Feature category involve all elements which have a defined location on the genome.

URL pattern:<version>/<species>/feature/<subcategory>/id/<resource|action>


URL pattern:<version>/<species>/feature/gene/gene1, gene2/<resource|action>
Gene format: we accept all id formats.
Resources or actions:

WS API Example Code

Today, the vast majority of programming languages can handle URLs, what makes RENATO Web Services API fully accessible in a programmatic way. Here we present an example of usage in Perl. The code below extracts the related diseases of a miRNA gene simply using the URL structure described avobe.
#!/usr/bin/perl -w
use strict;
## load LWP library and create UserAgent object
use LWP::Simple;
my $browser = LWP::UserAgent->new;
## define the query URL
my $url = '';
## send request
my $response = $browser->get($url);
## check the outcome
if ($response->is_success) {
	print $response->content;
}else {
	print "Error getting $url \n Error: ".$response->status_line."\n";
restful_web_services.txt · Last modified: 2012/07/06 16:11 by mbleda
Driven by DokuWiki Recent changes RSS feed Valid XHTML 1.0 do yourself a favour and use a real browser - get firefox!!