Example Java Client with Unirest

Setup Maven and Create a New Project

mvn archetype:generate -DgroupId=ensembl -DartifactId=EnsemblRestClient -DinteractiveMode=false

Edit the POM to add the Unirest dependency to <dependencies>

<dependency>
  <groupId>com.mashape.unirest</groupId>
  <artifactId>unirest-java</artifactId>
  <version>1.4.6</version>
</dependency>

Add the following instructions to your <project> section

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <configuration>
          <archive>
            <manifest>
              <mainClass>RestClient</mainClass>
            </manifest>
          </archive>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
        </configuration>
      </plugin>
    </plugins>
  </build>

The Client

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;
import org.json.JSONArray;
import org.json.JSONObject;

public class RestClient {

	private final String server;
	private final int requestPerSecond;
	private int requestCount = 0;
	private long limitStartTime = System.currentTimeMillis();

	public RestClient(String server, int requestPerSecond) {
		this.server = server;
		this.requestPerSecond = requestPerSecond;
	}

	public static void main(String[] args) throws InterruptedException, UnirestException {
		String species = "human";
		String symbol = "BRAF";
		if (args.length == 1) {
			species = args[0];
		} else if (args.length == 2) {
			species = args[0];
			symbol = args[1];
		}

		RestClient client = new RestClient("http://rest.ensembl.org", 15);
		client.printVariants(species, symbol);
	}

	public void printVariants(String species, String symbol) throws UnirestException, InterruptedException {
		String geneId = getGeneId(species, symbol);

		String url = String.format("%s/overlap/id/%s?feature=variation", server, geneId);
		JSONArray variants = fetchJson(url).getArray();
		for (int i = 0; i < variants.length(); i++) {
			JSONObject variant = variants.getJSONObject(i);
			String srName = variant.getString("seq_region_name");
			int start = variant.getInt("start");
			int end = variant.getInt("end");
			int strand = variant.getInt("strand");
			String id = variant.getString("id");
			String consequence = variant.getString("consequence_type");
			String output = String.format("%s:%d-%d:%d ==> %s (%s)", srName, start, end, strand, id, consequence);
			System.out.println(output);
		}
	}

	private String getGeneId(String species, String symbol) throws UnirestException, InterruptedException {
		String url = String.format("%s/xrefs/symbol/%s/%s?object_type=gene", server, species, symbol);
		JSONArray genes = fetchJson(url).getArray();

		if (genes.length() == 0) {
			throw new IllegalArgumentException(String.format("No gene id for %s symbol %s", species, symbol));
		} else {
			return genes.getJSONObject(0).getString("id");
		}
	}

	private JsonNode fetchJson(String url) throws UnirestException, InterruptedException {
		rateLimit();
		HttpResponse<JsonNode> response = Unirest.get(url)
				.header("Content-Type", "application/json")
				.asJson();
		String retryHeader = response.getHeaders().getFirst("Retry-After");

		if (response.getStatus() == 200) {
			return response.getBody();
		} else if (response.getStatus() == 429 && retryHeader != null) {
			Long waitSeconds = Long.valueOf(retryHeader);
			Thread.sleep(waitSeconds * 1000);
			return fetchJson(url);
		} else {
			throw new IllegalArgumentException("No data at " + url);
		}
	}

	private void rateLimit() throws InterruptedException {
		requestCount++;
		if (requestCount == requestPerSecond) {
			long currentTime = System.currentTimeMillis();
			long diff = currentTime - limitStartTime;
			//if less than a second has passed then sleep for the remainder of the second
			if (diff < 1000) {
				Thread.sleep(1000 - diff);
			}
			//reset
			limitStartTime = System.currentTimeMillis();
			requestCount = 0;
		}
	}
}

Building

Add the client to the directory src/main/java/ensembl in the maven generated project. Then build the JAR and run it.

mvn clean compile assembly:single
java -jar target/EnsemblRestClient-1.0-SNAPSHOT-jar-with-dependencies.jar

Credit

This client was contributed by Christoph Grabmüller. Many thanks