Overview

OpenCGA has a large and rich suite of web services to store and query almost anything imaginable in bioinformatics. As Java developers, we have created an OpenCGA client API to make really easy and straightforward calling those webservices, so new developers don't have to spend time implementing those calls, managing exceptions and converting the results into OpenCGA's data models. All these is managed automatically by the client API.

Library design

Developers only need to create an instance of the OpenCGAClient class passing the client configuration file (client-configuration.yml) as an argument and, optionally, the user and password or a valid token to start doing calls as an authenticated user. The only role of the OpenCGAClient class is to work as a factory of the actual clients.

OpenCGAClient opencgaClient = new OpenCGAClient(clientConfiguration);
OpenCGAClient opencgaClient = new OpenCGAClient("myUserId", "myPassword", clientConfiguration);
OpenCGAClient opencgaClient = new OpenCGAClient("myValidToken", clientConfiguration);

A different client class have been created for every single category present in the web services (user, project, study...). All the available clients can be retrieved as shown below:

UserClient userClient = opencgaClient.getUserClient();
ProjectClient projectClient = opencgaClient.getProjectClient();
StudyClient studyClient = opencgaClient.getStudyClient();
FileClient fileClient = opencgaClient.getFileClient();
JobClient jobClient = opencgaClient.getJobClient();
IndividualClient individualClient = opencgaClient.getIndividualClient();
SampleClient sampleClient = opencgaClient.getSampleClient();
VariableSetClient variableSetClient = opencgaClient.getVariableSetClient();
CohortClient cohortClient = opencgaClient.getCohortClient();
FamilyClient familyClient = opencgaClient.getFamilyClient();
ToolClient toolClient = opencgaClient.getToolClient();
AlignmentClient alignmentClient = opencgaClient.getAlignmentClient();
VariantClient variantClient = opencgaClient.getVariantClient();

Each client will contain specific methods for every single action that can be found in the web services apart from the most common ones (create, update, info, search...). Generally, all these methods will take the mandatory parameters individually and will accept a Map<String, Object> additionally to contain the optional ones. In this case, it is the developer's responsibility to have a look at the Swagger documentation to know which parameters can be passed in the map.

For example, if we wanted to get the information of two samples excluding the attributes and stats fields, we could do it as follows:

// Create the map to put the fields to be excluded in this case
Map<String, Object> myMap = new HashMap<>();
myMap.put("exclude", "attributes,stats");


// Make the query
QueryResponse<Sample> sampleQueryResponse = sampleClient.get("sample1,sample2", myMap);


How to add the dependency

At the moment, the only way to add OpenCGA client dependency is by downloading and compiling OpenCGA client module (https://github.com/opencb/opencga/blob/develop/opencga-client/pom.xml) to generate the needed jar file. In the future, the OpenCGA client will be added to the Maven Central Repository (https://search.maven.org).

Table of Contents: