Using RESTful web services

Using REST web services

In this tutorial you will learn how to query CellBase web services using different technologies and programming languages. You are encouraged to visit RESTful Web Services documentation to understand and learn how CellBase web services have been designed and implemented.

There are several public CellBase RESTful servers you can use. In this tutorial we will use EMBL-EBI CellBase host URL www.ebi.ac.uk/cellbase/webservices/rest but you can change it by any other host. You can also follow the Download and Installation and Load Data Models tutorials and install your own RESTful server, then you can use localhost:8080/cellbase/webservices/rest.

Technologies and programming languages:

• [curl](Using RESTful web services#using-curl)
• [Python](Using RESTful web services#using-python)
• [Java](Using RESTful web services#using-java)
• [R](Using RESTful web services#using-r)
• [Javscript](Using RESTful web services#using-javascript)

Using curl

curl is a command line tool and library for transferring data with URL syntax. It supports many different protocols including HTTP what allows to use it to query data.

• Get information of Human genes located in Chromosome 3 between coordinates 55 and 100000; execute

curl http://www.ebi.ac.uk/cellbase/webservices/rest/v3/hsapiens/genomic/region/3:55-100000/gene

• Get all Human variants associated with beta-Thalassemia:

curl http://www.ebi.ac.uk/cellbase/webservices/rest/v3/hsapiens/genomic/variant/beta_Thalassemia/phenotype

• Get information for all Drosophila Melanogaster chromosomes:

curl http://wwwdev.ebi.ac.uk/cellbase/webservices/rest/v3/dmelanogaster/genomic/chromosome/all

Using Python

Python is a general programming language that lets you work quickly and integrate systems more effectively. You can easily query RESTful web services using urllib2 library. This snippet retrieves all the human genes in a particular region.

#!/usr/bin/python

import urllib2
import json
import zlib

# Make the call to the server
url = 'http://wwwdev.ebi.ac.uk/cellbase/webservices/rest/v3/hsapiens/genomic/region/3:1104666-1166667/gene'
req = urllib2.Request(url)

# Inform to the server we accept gzip compression
req.add_header("Accept-Encoding", "gzip")

response = urllib2.urlopen(req)
json_data = response.read()

# Uncompress the gzip result
data = zlib.decompress(json_data, 16+zlib.MAX_WBITS)
data = json.loads(data)

print data

Using Java

import org.opencb.biodata.models.feature.Region;
import org.opencb.cellbase.core.client.CellBaseClient;
import org.opencb.cellbase.core.common.core.Gene;
import org.opencb.datastore.core.QueryOptions;
import org.opencb.datastore.core.QueryResponse;
import org.opencb.datastore.core.QueryResult;

public class CellBaseClientTest {
    public static void main(String[] args) throws URISyntaxException, IOException {
        CellBaseClient cellbaseClient = new CellbaseClient(
                "wwwdev.ebi.ac.uk", 80, "cellbase/webservices/rest/", "v3", "hsapiens");

        QueryResponse<QueryResult<Gene>> response =
                cellBaseClient.getGene(CellBaseClient.Category.genomic, CellBaseClient.SubCategory.region,
                Arrays.asList(new Region("3", 1104666, 1166667)), 
                new QueryOptions());

        System.out.println(response);
        return;
    }
}

import org.glassfish.jersey.client.ClientConfig;

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Invocation;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriBuilder;

import com.fasterxml.jackson.core.JsonFactory;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectReader;

public class CellBaseJerseyTest {

    private final ObjectMapper objectMapper = new ObjectMapper(new JsonFactory());
    private final Client client = ClientBuilder.newClient(new ClientConfig());

    public static void main(String[] args) throws URISyntaxException, IOException {
        Class<?> clazz = Gene.class;
        URI uri = new URI("http://wwwdev.ebi.ac.uk/cellbase/webservices/rest/v3/hsapiens/genomic/region/3:1104666-1166667/gene?of=json");
        UriBuilder uriBuilder = UriBuilder.fromUri(uri)

        Invocation.Builder request = client.target(uriBuilder).request();
        Response response = request.get();
        String responseStr = response.readEntity(String.class);

        ObjectReader responseReader = objectMapper.reader(objectMapper.getTypeFactory().constructParametricType(
                QueryResponse.class, objectMapper.getTypeFactory().constructParametricType(
                QueryResult.class, clazz))));

        QueryResponse<QueryResult<Gene>> response = responseReader.readValue(responseStr);

        System.out.println(response);
        return;
    }
}

Using R

R is a programming language and software environment widely used by statisticians and data analysts. You can easily query RESTful web services using RCurl and rjson libraries. This snippet retrieves all the human genes in a particular region.

library(RCurl)
library(rjson)

## Set URL
url <- 'http://wwwdev.ebi.ac.uk/cellbase/webservices/rest/v3/hsapiens/genomic/region/3:1104666-1166667/gene?exclude=transcripts'

## Retrieve data
response <- getURL(url)

## Transform JSON to list
json.data <- fromJSON(response)

## Count number of genes found
num.genes <- length(json.data$response[[1]]$result)
print( paste0("Number of genes found: ", num.genes))

## print genes
print("Genes:")
for (res in json.data$response[[1]]$result){
  print ( paste(res$name, res$id, res$biotype, sep = ", "))
}

Using JavaScript