- Created by Nacho Medina, last modified by Wasim Bari on Nov 08, 2017
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 18 Next »
Understanding the URL
The general structure of a OpenCGA RESTful URL call is:
http://HOST_URL/webservices/rest/{apiVersion}/{resource}/{id}/{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. *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.
APIVersion
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, ... |
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 |
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.
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.
Swagger
Swagger project has been set up and is available at:
Table of Contents:
- No labels