Http Request

A simple convenience library for using a HttpURLConnection to make requests and access the response.

This library is available under the MIT License.

Usage

The http-request library is available from Maven Central.

<dependency>
<groupId>com.github.kevinsawicki</groupId>
<artifactId>http-request</artifactId>
<version>6.0</version>
</dependency>

Not using Maven? Simply copy the HttpRequest class into your project, update the package declaration, and you are good to go.

Javadocs are available here.

FAQ

Who uses this?

See here for a list of known projects using this library.

Why was this written?

This library was written to make HTTP requests simple and easy when using a HttpURLConnection.

Libraries like Apache HttpComponents are great but sometimes for either simplicity, or perhaps for the environment you are deploying to (Android), you just want to use a good old-fashioned HttpURLConnection. This library seeks to add convenience and common patterns to the act of making HTTP requests such as a fluid-interface for building requests and support for features such as multipart requests.

Bottom line: The single goal of this library is to improve the usability of the HttpURLConnection class.

What are the dependencies?

None. The goal of this library is to be a single class class with some inner static classes. The test project does require Jetty in order to test requests against an actual HTTP server implementation.

How are exceptions managed?

The HttpRequest class does not throw any checked exceptions, instead all low-level exceptions are wrapped up in a HttpRequestException which extends RuntimeException. You can access the underlying exception by catching HttpRequestException and calling getCause() which will always return the original IOException.

Are requests asynchronous?

No. The underlying HttpUrlConnection object that each HttpRequest object wraps has a synchronous API and therefore all methods on HttpRequest are also synchronous.

Therefore it is important to not use an HttpRequest object on the main thread of your application.

Here is a simple Android example of using it from an AsyncTask:

privateclassDownloadTaskextendsAsyncTask<String, Long, File> {
protectedFiledoInBackground(String... urls) {
try {
HttpRequestrequest = HttpRequest.get(urls[0]);
Filefile = null;
if (request.ok()) {
file = File.createTempFile("download", ".tmp");
request.receive(file);
publishProgress(file.length());
}
returnfile;
} catch (HttpRequestExceptionexception) {
returnnull;
}
}
protectedvoidonProgressUpdate(Long... progress) {
Log.d("MyApp", "Downloaded bytes: " + progress[0]);
}
protectedvoidonPostExecute(Filefile) {
if (file != null)
Log.d("MyApp", "Downloaded file to: " + file.getAbsolutePath());
elseLog.d("MyApp", "Download failed");
}
}
newDownloadTask().execute("http://google.com");

Examples

Perform a GET request and get the status of the response

intresponse = HttpRequest.get("http://google.com").code();

Perform a GET request and get the body of the response

Stringresponse = HttpRequest.get("http://google.com").body();
System.out.println("Response was: " + response);

Print the response of a GET request to standard out

HttpRequest.get("http://google.com").receive(System.out);

Adding query parameters

HttpRequestrequest = HttpRequest.get("http://google.com", true, 'q', "baseball gloves", "size", 100);
System.out.println(request.toString()); // GET http://google.com?q=baseball%20gloves&size=100

Using arrays as query parameters

int[] ids = newint[] { 22, 23 };
HttpRequestrequest = HttpRequest.get("http://google.com", true, "id", ids);
System.out.println(request.toString()); // GET http://google.com?id[]=22&id[]=23

Working with request/response headers

StringcontentType = HttpRequest.get("http://google.com")
.accept("application/json") //Sets request header
.contentType(); //Gets response headerSystem.out.println("Response content type was " + contentType);

Perform a POST request with some data and get the status of the response

intresponse = HttpRequest.post("http://google.com").send("name=kevin").code();

Authenticate using Basic authentication

intresponse = HttpRequest.get("http://google.com").basic("username", "p4ssw0rd").code();

Perform a multipart POST request

HttpRequestrequest = HttpRequest.post("http://google.com");
request.part("status[body]", "Making a multipart request");
request.part("status[image]", newFile("/home/kevin/Pictures/ide.png"));
if (request.ok())
System.out.println("Status was updated");

Perform a POST request with form data

Map<String, String> data = newHashMap<String, String>();
data.put("user", "A User");
data.put("state", "CA");
if (HttpRequest.post("http://google.com").form(data).created())
System.out.println("User was created");

Copy body of response to a file

Fileoutput = newFile("/output/request.out");
HttpRequest.get("http://google.com").receive(output);

Post contents of a file

Fileinput = newFile("/input/data.txt");
intresponse = HttpRequest.post("http://google.com").send(input).code();

Using entity tags for caching

Filelatest = newFile("/data/cache.json");
HttpRequestrequest = HttpRequest.get("http://google.com");
//Copy response to filerequest.receive(latest);
//Store eTag of responseStringeTag = request.eTag();
//Later on check if changes existbooleanunchanged = HttpRequest.get("http://google.com")
.ifNoneMatch(eTag)
.notModified();

Using gzip compression

HttpRequestrequest = HttpRequest.get("http://google.com");
//Tell server to gzip response and automatically uncompressrequest.acceptGzipEncoding().uncompress(true);
Stringuncompressed = request.body();
System.out.println("Uncompressed response is: " + uncompressed);

Ignoring security when using HTTPS

HttpRequestrequest = HttpRequest.get("https://google.com");
//Accept all certificatesrequest.trustAllCerts();
//Accept all hostnamesrequest.trustAllHosts();

Configuring an HTTP proxy

HttpRequestrequest = HttpRequest.get("https://google.com");
//Configure proxyrequest.useProxy("localhost", 8080);
//Optional proxy basic authenticationrequest.proxyBasic("username", "p4ssw0rd");

Following redirects

intcode = HttpRequest.get("http://google.com").followRedirects(true).code();

Custom connection factory

Looking to use this library with OkHttp? Read here.

HttpRequest.setConnectionFactory(newConnectionFactory() {
publicHttpURLConnectioncreate(URLurl) throwsIOException {
if (!"https".equals(url.getProtocol()))
thrownewIOException("Only secure requests are allowed");
return (HttpURLConnection) url.openConnection();
}
publicHttpURLConnectioncreate(URLurl, Proxyproxy) throwsIOException {
if (!"https".equals(url.getProtocol()))
thrownewIOException("Only secure requests are allowed");
return (HttpURLConnection) url.openConnection(proxy);
}
});

Contributors

• Kevin Sawicki :: contributions
• Eddie Ringle :: contributions
• Sean Jensen-Grey :: contributions
• Levi Notik :: contributions
• Michael Wang :: contributions
• Julien HENRY :: contributions
• Benoit Lubek :: contributions
• Jake Wharton :: contributions
• Oskar Hagberg :: contributions
• David Pate :: contributions
• Anton Rieder :: contributions
• Jean-Baptiste Lièvremont :: contributions
• Roman Petrenko :: contributions