RESTful Web Services

Understanding the URL

The general structure of a OpenCGA RESTful URL call is:

http://HOST_URL/webservices/rest/{version}/{resource}/{id}/{endpoint}?{options}

Where HOST_URL is as follows http://bioinfodev.hpc.cam.ac.uk/opencga

Sections in braces are web service parameters, so they can be treated as variables.

Quick example:
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.

The available parameters are:

• version: indicates OpenCGA version to retrieve information from, data models and API may change between versions.
• resource: specifies the data type of what the user want to retrieve in the id field. This can be one of users, projects, studies, files, jobs, individuals, samples, variables, cohorts or tools, more information here.
• id: the resource id we want to query.
• endpoint: 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. More information here.
• 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.

Version

Versions are numbered as v1, v2, etc. At this moment we are heading to first stable version which is v1. However, when more versions are available in the future the latest stable version will be always coded as latest.

Resources and Endpoints

There are 10 different resources implemented:

Category	Description	Main Endpoints
users	Different methods to work with users	info, create, login, logout, ...
projects	projects are defined for each user and contains studies	info, create, studies, ...
studies	studies are the main component of catalog, the can be shared and contain files, samples and jobs	info, create, files, samples, jobs, variants, alignments, groups, ...
files	files are added to the study and can be indexed to be queried	info, create, index, share, ...
jobs	jobs are tool executions that can be queued	info, create, ...
individuals	samples come from the individuals	info, create, ...
samples	samples are each of the experiment samples, typically matches a NGS BAM file or VCF sample	info, create, annotate, share, ...
variables	variables annotate samples with different information useful for data analysis	info, crate, ...
cohorts	these model a group of samples that share some common properties, these are used for data analysis	info, create, stats, samples, ...
tools	bioinformatics tools installed for data analysis	info, help, ...

For more detailed information about resources, endpoints and options OpenCGA has been documented using Swagger project, it is available at:

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

IDs

This is the query parameter and the type matches resources path parameter, it represents the resource about we want to retrieve the information.

NOTE: In order to improve performance in many cases ID lists can be passed together in only one REST call separated by commas. Only 200 IDs are allowed.

Swagger

Swagger project has been set up and is available at:

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