Overview

The OpenCGA JavaScript client has been developed following the ES6 standard using classes. All the methods from the API calling to the web services return promises where developers can attach the necessary callbacks to.

Library design

The OpenCGA client file can be found in https://github.com/opencb/jsorolla/blob/develop/src/core/clients/opencga-client.js. The file can be divided into two main parts, the configuration and the actual client. The OpenCGAClientConfig configuration class is a really small class containing some fields to know mainly, where the REST host can be found. Additionally, the developer can choose whether to let the OpenCGA client to use cookies to store the main credentials allowing to easily refresh the page without loosing the authentication credentials and set a cookie prefix. 

// Initialise the OpenCGA config
let myConfig = new OpenCGAClientConfig("localhost:8080/opencga");

The second part of the file is composed by the actual OpenCGA client. The same approach followed to implement the Java client was followed here. We have implemented an OpenCGAClient class that acts as a resource factory. There exist one class for each available resource (user, project, study) that can be invoked through the OpenCGAClient instance as shown in the example.

// Initialise the OpenCGAClient
let openCGAClient = new OpenCGAClient(myConfig);


// Get an instance of all the possible resources
let userClient = openCGAClient.users();
let projectClient = openCGAClient.projects();
let studyClient = openCGAClient.studies();
let fileClient = openCGAClient.files();
let jobClient = openCGAClient.jobs();
let sampleClient = openCGAClient.samples();
let individualClient = openCGAClient.individuals();
let familyClient = openCGAClient.families();
let cohortClient = openCGAClient.cohorts();
let clinicalAnalysisClient = openCGAClient.clinical();
let variableSetClient = openCGAClient.variables();
let alignmentClient = openCGAClient.alignments();
let variantClient = openCGAClient.variants();

Every method belonging to each resource takes the mandatory parameters individually. Calls to webservices using the GET method usually takes an additional params field containing any of the additional optional parameters. Calls via POST takes an additional body field containing the required information to be sent in the body of the message apart from the params field. Both params and body should be JSON objects containing the previously described information. The list of accepted parameters and fields should be checked in the Swagger documentation.

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

sampleClient.info("sample1,sample2", {"exclude": "attributes,stats"})
.then(function(response) {
  // Success
  console.log(response);
}).catch(function(e) {
  // Error
  console.log(e);
});

How to use the Javascript client

In order to use the Javascript client, developers will only need to include two files which can be found in https://github.com/opencb/jsorolla/blob/develop/src/core/clients. Additionally, OpenCGA client depends on two external libraries, crypto-js (tested with version 3.1.8) and cookies-js (tested with version 1.1.0).

In the future, it will be possible to add this client as an npm dependency (https://www.npmjs.com/~opencb).

<!-- OpenCGA dependencies -->
<script type="text/javascript" src="../node_modules/crypto-js/crypto-js.js"></script>
<script type="text/javascript" src="../node_modules/cookies-js/src/cookies.js"></script>
<!-- !OpenCGA dependencies -->

<!-- OpenCGA client -->
<script type="text/javascript" src="rest-client.js"></script>
<script type="text/javascript" src="opencga-client.js"></script>
<!-- !OpenCGA client -->