Skip to content

RESTful Web Services

Jump to bottom
Nacho edited this page Aug 27, 2015 · 10 revisions

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: this 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 Gene, SNP, Transcript, Protein, Xref, ...
studies Regulatory category refers to all regulatory interactions involving transcription factors and microRNAs TFBSs, miRNAs
files Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome Pathway
jobs Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome Pathway
individuals Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome Pathway
samples Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome Pathway
variables Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome Pathway
cohorts Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome Pathway
tools Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome Pathway

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/

Id

This is the query parameter, it is the feature or term about we want to retrieve the information (resource). Its type must correspond with the subcategory.

NOTE: In order to improve performance, ID lists can be passed together in only one REST call separated by commas. Only 200 IDs are allowed. For larger queries user the CellBase client.

Examples:

Resources

Each Category and Subcategory can have different resources and actions allowed. They specify the type of result we want to obtain from the ID.

Examples:

NOTE: Resources must always be written in singular.

Filters and extra options

Filters and extra options can be added at the end of the REST query followed by ?. They are optional and can be combined using the & sign. E.g:
bioinfo.hpc.cam.ac.uk/cellbase/webservices/rest/latest/hsapiens/feature/gene/BRCA2/info?of=json&include=id,name,biotype

These are the available filters and options:

Help and metadata

The available main categories are listed at:
bioinfo.hpc.cam.ac.uk/cellbase/webservices/rest/latest/hsapiens

And the available subcategories for a main category are listed at:

Subcategories should specify the type of the id. Subcategories can be different for each category and are described within each of the categories mentioned above.

Each subcategory usage is shown by writing the subcategory name followed by /help, for example:

bioinfo.hpc.cam.ac.uk/cellbase/webservices/rest/latest/hsapiens/feature/gene/help

Swagger

Swagger project has been set up and is available at:

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

OpenCGA is an open source project and it is freely available.

General

OpenCGA Catalog

OpenCGA Storage

About

Clone this wiki locally