General Consideration

Understanding the URL

The general format of the REST API web services is: 

http://HOST_URL/webservices/rest/{apiVersion}/{resource}/{id(s)}/{endpoint}?{options}

where HOST_URL is the name of the host machine and the name of Java war file deployed in web server (eg. tomcat) over that server for example bioinfodev.hpc.cam.ac.uk/opencga

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

http://bioinfodev.hpc.cam.ac.uk/opencga/webservices/rest/v1/users/opencga/login?password=opencga

As is explained later in this documentation, this RESTful web service will login user opencga.

• apiVersion (v1) : indicates OpenCGA version to retrieve information from, data models and API may change between versions. 
• resource (users) : specifies the data type of what the user wants to retrieve in the id field. This can be one of resources listed below. 
• id (opencga) : the resource id we want to query. 
• endpoint (login) : these parameters must be specified depending on the nature of your input data. For example, if we want to query all files by a specific study (e.g. 1000genomes) we should use the studies resource and files endpoint. 
• options (password) : variables in key value pair form, passed as query parameters.

URL parameters

apiVersion

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

resource

There are several resources implemented, see below.

ids

This is the query parameter and the type matches resources path parameter, this is a unique identifier for the resource we are interacting. Plural means a list of IDs can be passed to improve performance with a single REST call separated by commas rather than multiple calls. OpenCGA preserves the order of the results with corresponding IDs. A Boolean variable, silent, can be set to indicate either if user is interested to receive partial results (true) as well or only expects complete set of results or nothing in case of any failure (resource doesn't exist, permission denied etc). As a trade off between performance and ease of use a maximum of 100 IDs are allowed in one web service.

options

These query parameters can modify the behaviour of the query (exclude, include, limit, skip 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. 

Image Removed

Resources and Endpoints

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

Catalog

Analysis

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

Swagger

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

http://bioinfodev.hpc.cam.ac.uk/opencga/webservices/

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.

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.

Image RemovedThere are three main ways to access OpenCGA data:

• RESTful Web Services and Clients
• Command Line Interface (CLI)
• Web data portal