#Requests

Requests is a http request lib for human beings who use java inspired by python requests module. The Httpclient lib is greate, but has too complex API, which confuse beginners. Requests build simple and flexible api, both for common and advanced Usage.

#User Guide ##Get Requests Requests is now in maven central repo.

<dependency>
    <groupId>net.dongliu</groupId>
    <artifactId>requests</artifactId>
    <version>1.8.5</version>
</dependency>

##Make request Simple example that do http get request:

String url = ...;
Response<String> resp = Requests.get(url).text();

Post and other method:

resp = Requests.post(url).text();
resp = Requests.head(url).text();
resp = Requests.delete(url).text();
resp = Requests.options(url).text();

##Response Content The response object have common http response field to be used:

Response<String> resp = Requests.get(url).text();
int statusCode = resp.getStatusCode();
Headers headers = resp.getHeaders();
Cookies cookies = resp.getCookies();
String body = resp.getBody();

The text() method here trans http response body as String, there are other method to process http response:

// get response as string, and use provided encoding
Response<String> resp = Requests.get(url).text("UTF-8");
// get response as bytes
Response<byte[]> resp1 = Requests.get(url).bytes();
// save response as file 
Response<File> resp2 = Requests.get(url).file("/path/to/save/file");

or you can custom http response processor your self:

Response<String> resp = Requests.get(url).handler(new ResponseHandler<String>() {
    @Override
    public String handle(int statusCode, Headers headers, InputStream in)
            throws IOException {
        return null;
    }
});

##Passing Parameters You can pass parameters in urls use param or params method:

Map<String, Object> params = new HashMap<>();
params.put("k1", "v1");
params.put("k2", "v2");
Response<String> resp = Requests.get(url)
        .param("key1", "value1").params(params)
        //.params(new Parameter(...), new Parameter(...))
        .text();

##Custom Headers Http request headers can be set by header or headers method:

Map<String, Object> headers = new HashMap<>();
headers.put("k1", "v1");
headers.put("k2", "v2");
Response<String> resp = Requests.get(url)
        .header("key1", "value1").headers(headers)
        //.headers(new Header(...), new Header(...))
        .text();

##Cookies Cookies can be add by::

Map<String, Object> cookies = new HashMap<>();
cookies.put("k1", "v1");
cookies.put("k2", "v2");
Response<String> resp = Requests.get(url)
        .cookie("key1", "value1").cookies(cookies)
        //.cookies(new Cookie(...), new Cookie(...))
        .text();

##UserAgent A convenient method to set userAgent:

Response<String> resp = Requests.get(url).userAgent(userAgent).text();

##Request with data Http Post, Put, Patch method can send request bodys. Take Post for example:

Map<String, Object> formData = new HashMap<>();
formData.put("k1", "v1");
formData.put("k2", "v2");
// send form-encoded data. x-www-form-urlencoded header will be send automatically
Response<String> resp = Requests.post(url).data(formData).text();
// send string data
String str = ...;
resp = Requests.post(url).data(str, "UTF-8").text();
// send from inputStream
InputStream in = ...
resp = Requests.post(url).data(in).text();

One more complicate situation is multiPart post request, this can be done via multiPart method:

Map<String, Object> formData = new HashMap<>();
formData.put("k1", "v1");
formData.put("k2", "v2");
// send form-encoded data
Response<String> resp = Requests.post(url).data(formData).multiPart("ufile", "/path/to/file")
        .multiPart(..., ...).text();

###Redirection Requests will handle 301/302 http redirect, you can get redirect history:

Response<String> resp = Requests.get(url).text();
List<URI> history = resp.getHistory();

Or you can disable automatic redirect and handle it yourself:

Response<String> resp = Requests.get(url).allowRedirects(false).text();

Timeout

There are two timeout parameters you can set, connect timeout, and socket timeout. The timeout value default to 10_1000 milliseconds.

// both connec timeout, and socket timeout
Response<String> resp = Requests.get(url).timeout(30_1000).text();
// set connect timeout and socket timeout
resp = Requests.get(url).timeout(30_1000, 30_1000).text();

You may not need to know, but Requests also use connect timeout as the timeout value get connection from connection pool if connection pool is used. ##Gzip Requests send Accept-Encoding: gzip, deflate, and handle gzipped response in default. You can disable this by:

Response<String> resp = Requests.get(url).gzip(false).text();

##Https Verification Some https sites do not have trusted http certificate, Exception will be throwed when request. You can disable https certificate verify by:

Response<String> resp = Requests.get(url).verify(false).text();

##Basic Auth Set http basic auth param by auth method:

Response<String> resp = Requests.get(url).auth("user", "passwd").verify(false).text();

##Proxy Set proxy by proxy method:

Response<String> resp = Requests.get("http://www.baidu.com/")
        .proxy(Proxy.httpProxy("127.0.0.1", 8080))
        .text();

The proxy can be created by:

//http proxy
Proxy.httpProxy("127.0.0.1", 8080)
//https proxy
Proxy.httpsProxy("127.0.0.1", 8080)
//socket proxy
Proxy.httpsProxy("127.0.0.1", 5678)
//with auth
Proxy.httpProxy("127.0.0.1", 8080, userName, password)

##Exceptions Requests wrapped checked exceptions into runtime exception, RuntimeIOException, InvalidUrlException, IllegalEncodingException. Catch this if you mind.

Session

Session keep cookies and basic auto cache and other http context for you, useful when need login or other situations.Session have exactly the same usage as Requests.

Session session = Requests.session();
Response<String> resp1 = session.get(url1).text();
Response<String> resp2 = session.get(url2).text();

##Connection Pool Request(and Session) can share one connection pool to reuse http connections.

ConnectionPool connectionPool = ConnectionPool.custom().verify(false)
       .maxPerRoute(20)
       .maxTotal(100)
       //.proxy(...)
       .build();
Response<String> resp1 = Requests.get(url1).connectionPool(connectionPool).text();
Response<String> resp2 = Requests.get(url2).connectionPool(connectionPool).text();
connectionPool.close();

Note:

• you need to close connection pool manually when do not need it any more.
• if connection pool is used, you should set verify and proxy use ConnectionPoolBuilder, the connection pool's (verify, proxy) settings will override requests' settings.