Understanding the URL
The general structure of a OpenCGA RESTful URL call is:
http://HOST_URL/webservices/rest/{apiVersion}/{resource}/{id(s)}/{endpoint}?{options}
Where HOST_URL is as follows 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: *apiVersion*: 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.
APIVersion
ApiVersions are numbered as v1, v2, etc. At this moment we are heading to first stable apiVersion which is v1. However, when more apiVersions are available in the future the latest stable apiVersion 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, ... |
| 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, ... |
| families | families are connected collection of individuals based on relationship | 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, ... |
| cohorts | these model a group of samples that share some common properties, these are used for data analysis | info, create, stats, samples, ... |
| clinical Analysis | this handles creating and search of a clinical analysis | info, create, ... |
| variableSet | variables annotate samples with different information useful for data analysis | info, crate, ... |
| analysis alignment | web services to facilitate the alignment process | index, query, stats, coverage |
| analysis variant | web services to facilitate complete variant analysis using different handy methods | index, stats, query, validate, ibs, facet, samples, metadata |
| analysis tool | bioinformatics tools installed for data analysis | execute |
| Meta | gives the meta information about OpenCGA installation instance | ping, about, status |
| GA4GH | GA4GH standard web services to search genomics data in OpenCGA | variant search, reads search, responses |
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.
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.
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
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. OpenCGA supports deprecated services for two releases (Deprecated and Next one) and all deprecated web services are clearly marked as deprecated along with a warning help message for user.
Table of Contents: