-
Notifications
You must be signed in to change notification settings - Fork 53
RESTful web services
The general structure of a CellBase RESTful call is:
wwwdev.ebi.ac.uk/cellbase/rest/{version}/{species}/{category}/{subcategory}/{id}/{resource}?{filters}
Sections in braces are parameters, so they can be treated as variables.
Example:
wwwdev.ebi.ac.uk/cellbase/webservices/rest/latest/hsapiens/feature/gene/BRCA2/info
As is explained later in this documentation, this RESTfull WS will get all the information available for the gene BRCA2 in human using the latest version.
The available parameters are:
-
version: indicate the CellBase version to retrieve information from. More information here. -
species: species to get information from. More information about the available species and assemblies here. -
categoryandsubcategory: these parameters must be specified depending on the nature of your input data. For example, if we want to query CellBase by a genomic region (e.g. 13:32889575-32889763) we should use the genomic category and region subcategory. More information here. -
id: the user query. More information here.
*resource: what the user want to retrieve from theid. More information here.
Versions are numbered as v1, v2, v3, etc. At this moment the latest stable version is v3. However, the latest stable version will be always coded as latest.
A list of the species available for version v3 can be found here Use the abbreviated code to indicate the species. For example, hsapiens for Homo sapiens or mmusculus for Mus musculus.
There are 4 main categories:
| Category | Description | Subcategories |
|---|---|---|
| Genomic | Genomic category makes reference to genomic coordinates | Position, Variant, Region |
| Feature | Feature category involve all elements which have a defined location on the genome and provides an easy way to retrieve cross references for an ID | Gene, SNP, Transcript, Protein, Xref, ... |
| Regulatory | Regulatory category refers to all regulatory interactions involving transcription factors and microRNAs | TFBSs, miRNAs |
| Network | Network category makes reference to all types of networks and pathways, including the protein interactome, the regulatory network and Reactome | Pathway |
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:
wwwdev.ebi.ac.uk/cellbase/webservices/rest/latest/hsapiens/genomic/region/3:1000-200000,X:35-459000,4:2334-5555/gene
wwwdev.ebi.ac.uk/cellbase/webservices/rest/latest/hsapiens/feature/gene/BRCA2,BCL2,P53/snp
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:
wwwdev.ebi.ac.uk/cellbase/webservices/rest/latest/hsapiens/feature/gene/BRCA2/transcript
wwwdev.ebi.ac.uk/cellbase/webservices/rest/latest/hsapiens/genomic/region/3:1000-200000/gene
wwwdev.ebi.ac.uk/cellbase/webservices/rest/latest/hsapiens/genomic/region/3:100000-200000/snp
NOTE: Resources must always be written in singular.
Users can add filters or extra-options to the REST query. Some of them can be applied to all queries, but some of them are specific of each subcategory.
-
General options (all of them are optional):
-
output format: coded as of, allowed values are: text, json, zip. Default: text. i.e.:
wwwdev.ebi.ac.uk/cellbase/webservices/rest/latest/hsapiens/genomic/region/3:1000-200000/gene?of=json
-
-
separator: the character to separate column in results. By default: tab.- //user//: in case of private version.
- //password//: in case of private version.
- Specific options: Every resource or action may have different filters or options, which are described in each category and subcategory.\ Examples:\ ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/genomic/region/3:1000-2000000/gene?biotype=protein_coding,mirna_gene http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/genomic/region/3:1000-2000000/gene?biotype=protein_coding,mirna_gene\ ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/genomic/region/12:400000-500000/snp?consequence_type=non_synonymous_codon,splice_region_variant http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/genomic/region/12:400000-500000/snp?consequence_type=non_synonymous_codon,splice_region_variant
===== Help and metadata ===== The available main categories are listed at:
''http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/''
And the available subcategories from a main category are listed at:
''http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/genomic''\ ''http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/feature''\ ''http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/regulatory''\ ''http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/network''
Subcategories should specify the type of the //id field//. Subcategories can be different for each category and are described within each of the categories mentioned above.
Each subcategory usage is shown by writting the subcategory name with ''/help'', for example:
''http://ws.bioinfo.cipf.es/cellbase/rest/latest/hsa/feature/gene/help''
Swagger project has been set up and is available at: