Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

General Consideration

Understanding the URL

The general format of the REST API web services is: 

OpenCGA RESTful URL Structure

where HOST_URL is the name of the host machine and the name of Java war file deployed in web server (e.g. tomcat) over that server for example localhost:8080/bionetdb

Entities inside the curly braces { } are the web service parameters, and they are treated as variables. For example the following URL:

Quick Example
http://localhost:8080/bionetdb/webservices/rest/v1/table/cypher?query="match (n:VARIANT) return count(n)"

As is explained later in this documentation, this RESTful web service will execute a Cypher query returning results as a table:

  • apiVersion (v1) : indicates BioNetDB version to retrieve information from, data models and API may change between versions. 
  • resource (table) : specifies the data type of what the user wants to retrieve. This can be one of resources listed below. 
  • endpoint (cypher) : these parameters must be specified depending on the nature of your input data; in our example, cypher indicates we are going to execute a Cypher query. 
  • options (query) : variables in key value pair form, passed as query parameters; in our example, it is the Cypher query itself: "match (n:VARIANT) return count(n)"

URL parameters


apiVersions are numbered as v1v2, etc. At this moment we are heading to first stable apiVersion which is v1.


There are several resources implemented, see below.


These query parameters can modify the behaviour of the query (excludeincludelimitskip and count) or add some filters to some specific endpoints to add useful functionality. The following image shows some typical options for a certain web service. 

Resources and Endpoints

REST API is organised in two main groups: Catalog and Analysis web services. 


CategoryPathDescriptionMain Endpoints
Users/usersDifferent methods to work with usersinfo, create, login, ...
Projects/projectsprojects are defined for each user and contains studiesinfo, create, studies, ...
Studies/studiesstudies are the main component of catalog, the can be shared and contain files, samples and jobsinfo, create, files, samples, jobs, variants, alignments, groups, ...
Files/filesfiles are added to the study and can be indexed to be queriedinfo, create, index, share, ...
Jobs/jobsjobs are tool executions that can be queuedinfo, create, ...
Families/familiesfamilies are connected collection of individuals based on relationshipinfo, create, ...
Individuals/individualssamples come from the individualsinfo, create, ...
Samples/samplessamples are each of the experiment samples, typically matches a NGS BAM file or VCF sampleinfo, create, annotate, share, ...
Cohorts/cohortsthese model a group of samples that share some common properties, these are used for data analysisinfo, create, stats, samples, ...
Clinical Analysis/clinicalthis handles creating and search of a clinical analysisinfo, create, ...
Variable Set/variablesetvariables annotate samples with different information useful for data analysisinfo, crate, ...
Meta/metagives the meta information about OpenCGA installation instanceping, about, status
GA4GH/ga4ghGA4GH standard web services to search genomics data in OpenCGAvariant search, reads search, responses


CategoryPathDescriptionMain Endpoints
Analysis Alignment/analysis/alignmentOperations over Read Alignments to facilitate complete analysis with different tools.index, query, stats, coverage
Analysis Variant/analysis/variant

Operations over Genomic Variants to facilitate complete analysis with different tools.

index, stats, query, validate, ibs, facet, samples, metadata
Analysis Tool/analysis/toolbioinformatics tools installed for data analysisexecute


OpenCGA has been documented using Swagger project. Detailed information about resourcesendpoints and options is available at:

Client Libraries

Currently OpenCGA supports the following client libraries: 

  1. Java
  2. Python
  3. R
  4. JavaScript

Deprecation Policy

Certain APIs are deprecated over the period of time as OpenCGA is a live project and continuously improved and new features are implemented. Deprecation cycle consists of a warning period to let make user aware that these services are considered for change and highly likely will be replaced followed by a deprecated message. OpenCGA supports deprecated services for two releases (Deprecated and Next one). Deprecated services are hidden in the following release of deprecation and finally removed completely in next release.

Deprecation Life Cycle
Warning (working) ---> Deprecated (working) ---> Hidden (working) ---> Removed (not working) 

All deprecated web services are clearly marked as deprecated along with a warning help message for user.

Table of Contents:

  • No labels