The RapidAPI Developer Hub

Welcome to the RapidAPI developer hub. You'll find comprehensive guides and documentation to help you start working with RapidAPI as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Guides

Installing & Making a Request

With Maven

You can use Maven by including the library:

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

There are dependencies for Unirest-Java, these should be already installed, and they are as follows:

<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpclient</artifactId>
  <version>4.3.6</version>
</dependency>
<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpasyncclient</artifactId>
  <version>4.0.2</version>
</dependency>
<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpmime</artifactId>
  <version>4.3.6</version>
</dependency>
<dependency>
  <groupId>org.json</groupId>
  <artifactId>json</artifactId>
  <version>20140107</version>
</dependency>

If you would like to run tests, also add the following dependency along with the others:

<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.11</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.4</version>
  <scope>test</scope>
</dependency>

Without Maven

Alternatively if you don't use Maven, you can directly include the JAR file in the classpath: http://oss.sonatype.org/content/repositories/releases/com/mashape/unirest/unirest-java/1.4.9/unirest-java-1.4.9.jar

Don't forget to also install the dependencies (org.json, httpclient 4.3.6, httpmime 4.3.6, httpasyncclient 4.0.2) in the classpath too.

There is also a way to generate a Unirest-Java JAR file that already includes the required dependencies, but you will need Maven to generate it. Follow the instructions at http://blog.mashape.com/post/69117323931/installing-unirest-java-with-the-maven-assembly-plugin

HttpResponse<JsonNode> response = Unirest.post(API_URL)
.header("X-RapidAPI-Key", API_KEY)
.queryString("parameter", "value")
.field("parameter", "value")
.asJson();

Requests are made when asType is invoked, possible types include Json, Binary, String, Object.

If the request supports and it is of type HttpRequestWithBody, a body it can be passed along with .body(String|JsonNode|Object). For using .body(Object) some pre-configuration is needed (see below).

If you already have a map of parameters or do not wish to use separate field methods for each one there is a .fields(Map<String, Object> fields) method that will serialize each key - value to form parameters on your request.

.headers(Map<String, String> headers) is also supported in replacement of multiple header methods.

Route Parameters

Sometimes you want to add dynamic parameters in the URL, you can easily do that by adding a placeholder in the URL, and then by setting the route parameters with the routeParam function, like:

Unirest.get(API_URL + "/{placeholder}")
  .routeParam("placeholder", "value")
  .asJson();

Asynchronous Requests

Future<HttpResponse<JsonNode>> future = HttpResponse<JsonNode> response = Unirest.post(API_URL)
  .header("X-RapidAPI-Key", API_KEY)
  .queryString("parameter", "value")
  .field("parameter", "value")
  .asJsonAsync(new Callback<JsonNode>() {

    public void failed(UnirestException e) {
        System.out.println("The request has failed");
    }

    public void completed(HttpResponse<JsonNode> response) {
         int code = response.getStatus();
         Map<String, String> headers = response.getHeaders();
         JsonNode body = response.getBody();
         InputStream rawBody = response.getRawBody();
    }

    public void cancelled() {
        System.out.println("The request has been cancelled");
    }

});

File Uploads

HttpResponse<JsonNode> response = HttpResponse<JsonNode> response = Unirest.post(API_URL)
  .header("X-RapidAPI-Key", API_KEY)
  .queryString("parameter", "value")
  .field("content", new File("/path/to/file"))
  .asJson();

Advanced Configuration

You can set some advanced configuration to tune Unirest-Java:

Custom HTTP clients

You can explicitly set your own HttpClient and HttpAsyncClient implementations by using the following methods:

Unirest.setHttpClient(httpClient);
Unirest.setAsyncHttpClient(asyncHttpClient);

Timeouts

You can set custom connection and socket timeout values (in milliseconds):

Unirest.setTimeouts(long connectionTimeout, long socketTimeout);

By default the connection timeout (the time it takes to connect to a server) is 10000, and the socket timeout (the time it takes to receive data) is 60000. You can set any of these timeouts to zero to disable the timeout.

Default Request Headers

You can set default headers that will be sent on every request:

Unirest.setDefaultHeader("Header1", "Value1");
Unirest.setDefaultHeader("Header2", "Value2");

You can clear the default headers anytime with:

Unirest.clearDefaultHeaders();

Concurrency

You can set custom concurrency levels if you need to tune the performance of the syncronous or asyncronous client:

Unirest.setConcurrency(int maxTotal, int maxPerRoute);

By default the maxTotal (overall connection limit in the pool) is 200, and the maxPerRoute (connection limit per target host) is 20.

Exiting an application

Unirest starts a background event loop and your Java application won't be able to exit until you manually shutdown all the threads by invoking:

Unirest.shutdown();