Unirest is a set of lightweight HTTP libraries available in multiple languages, ideal for most applications:
- Make
GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONSrequests - Both syncronous and asynchronous (non-blocking) requests
- It supports form parameters, file uploads and custom body entities
- Easily add route parameters without ugly string concatenations
- Supports gzip
- Supports Basic Authentication natively
- Customizable timeout
- Customizable default headers for every request (DRY)
- Customizable
HttpClientandHttpAsyncClientimplementation - Automatic JSON parsing into a native object for JSON responses
Created with love by thefosk @ mashape.com
Is easy as pie. Kidding. It's about as easy as doing these little steps:
You can use Maven by including the library:
<dependency>
<groupId>com.mashape.unirest</groupId>
<artifactId>unirest-java</artifactId>
<version>1.3.22</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.4</version>
</dependency>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpasyncclient</artifactId>
<version>4.0.1</version>
</dependency>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpmime</artifactId>
<version>4.3.4</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>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.3.21/unirest-java-1.3.22.jar
Don't forget to also install the dependencies (org.json, httpclient 4.3.4, httpmime 4.3.4, httpasyncclient 4.0.1) 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
So you're probably wondering how using Unirest makes creating requests in Java easier, here is a basic POST request that will explain everything:
HttpResponse<JsonNode> jsonResponse = Unirest.post("http://httpbin.org/post")
.header("accept", "application/json")
.field("parameter", "value")
.field("foo", "bar")
.asJson();Requests are made when as[Type]() is invoked, possible types include Json, Binary, String. If the request supports and it is of type HttpRequestWithBody, a body it can be passed along with .body(String|JsonNode). If you already have a map of parameters or do not wish to use seperate 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.
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("http://httpbin.org/{method}")
.routeParam("method", "get")
.field("name", "Mark")
.asJson();In the example above the final URL will be http://httpbin.org/get - Basically the placeholder {method} will be replaced with get.
The placeholder's format is as easy as: {custom_name}
Sometimes, well most of the time, you want your application to be asynchronous and not block, Unirest supports this in Java using anonymous callbacks, or direct method placement:
Future<HttpResponse<JsonNode>> future = Unirest.post("http://httpbin.org/post")
.header("accept", "application/json")
.field("param1", "value1")
.field("param2", "value2")
.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.getCode();
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");
}
});Creating multipart requests with Java is trivial, simply pass along a File Object as a field:
HttpResponse<JsonNode> jsonResponse = Unirest.post("http://httpbin.org/post")
.header("accept", "application/json")
.field("parameter", "value")
.field("file", new File("/tmp/file"))
.asJson();HttpResponse<JsonNode> jsonResponse = Unirest.post("http://httpbin.org/post")
.header("accept", "application/json")
.body("{\"parameter\":\"value\", \"foo\":\"bar\"}")
.asJson();Authenticating the request with basic authentication can be done by calling the basicAuth(username, password) function:
HttpResponse<JsonNode> response = Unirest.get("http://httpbin.org/headers").basicAuth("username", "password").asJson();The Java Unirest library follows the builder style conventions. You start building your request by creating a HttpRequest object using one of the following:
GetRequest request = Unirest.get(String url);
GetRequest request = Unirest.head(String url);
HttpRequestWithBody request = Unirest.post(String url);
HttpRequestWithBody request = Unirest.put(String url);
HttpRequestWithBody request = Unirest.patch(String url);
HttpRequestWithBody request = Unirest.options(String url);
HttpRequestWithBody request = Unirest.delete(String url);Upon recieving a response Unirest returns the result in the form of an Object, this object should always have the same keys for each language regarding to the response details.
.getCode()- HTTP Response Status Code (Example 200).getHeaders()- HTTP Response Headers.getBody()- Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays..getRawBody()- Un-parsed response body
You can set some advanced configuration to tune Unirest-Java:
You can explicitly set your own HttpClient and HttpAsyncClient implementations by using the following methods:
Unirest.setHttpClient(httpClient);
Unirest.setAsyncHttpClient(asyncHttpClient);You can set custom connection and socket timeout values (in milliseconds):
Unirest.setTimeouts(long connectionTimeout, long socketTimeout);By default the connection timeout is 10000, and the socket timeout is 60000.
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();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();