Overview

OpenCGA has a large and rich suite of web services to store and query almost anything imaginable in bioinformatics. Because, calling those web services directly from Java could be a painAs Java developers, we have designed and implemented a Java API client really easy to use even for non expertscreated 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 call 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...). The list of all All the available clients can be found retrieved as shown below:

UserClient userClient = opencgaClient.getUserClient();
ProjectClient userClientprojectClient = opencgaClient.getProjectClient();
StudyClient userClientstudyClient = opencgaClient.getStudyClient();
FileClient userClientfileClient = opencgaClient.getFileClient();
JobClient userClientjobClient = opencgaClient.getJobClient();
IndividualClient userClientindividualClient = opencgaClient.getIndividualClient();
SampleClient userClientsampleClient = opencgaClient.getSampleClient();
VariableSetClient userClientvariableSetClient = opencgaClient.getVariableSetClient();
CohortClient userClientcohortClient = opencgaClient.getCohortClient();
FamilyClient userClientfamilyClient = opencgaClient.getFamilyClient();
ToolClient userClienttoolClient = opencgaClient.getToolClient();
AlignmentClient userClientalignmentClient = opencgaClient.getAlignmentClient();
VariantClient userClientvariantClient = opencgaClient.getVariantClient();

These clients will inherit the implementation of the most common actions from an abstract parent class called CatalogClient. 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).