A Guide to OkHttp

1. Introduction

In this tutorial, we’ll explore the basics of sending different types of HTTP requests, and receiving and interpreting HTTP responses. Then we’ll learn how to configure a Client with OkHttp.

Finally, we’ll discuss the more advanced use cases of configuring a client with custom headers, timeouts, response caching, etc.

2. OkHttp Overview

OkHttp is an efficient HTTP & HTTP/2 client for Android and Java applications.

It comes with advanced features, such as connection pooling (if HTTP/2 isn’t available), transparent GZIP compression, and response caching, to avoid the network completely for repeated requests.

It’s also able to recover from common connection problems; on a connection failure, if a service has multiple IP addresses, it can retry the request to alternate addresses.

At a high level, the client is designed for both blocking synchronous calls and nonblocking asynchronous calls.

OkHttp supports Android 2.3 and above. For Java, the minimum requirement is 1.7.

Now that we’ve given a brief overview, let’s see some usage examples.

3. Maven Dependency

First, let’s add the okhttp dependency to the pom.xml:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>5.0.0-alpha.12</version>
</dependency>

The okhttp dependency provides an HTTP client implementation for Java.

4. Synchronous GET With OkHttp

To send a synchronous GET request, we need to build a Request object based on a URL and make a Call. After its execution, we’ll get an instance of Response back:

@Test
public void whenGetRequest_thenCorrect() throws IOException {
    Request request = new Request.Builder()
      .url(BASE_URL + "/date")
      .build();

    Call call = client.newCall(request);
    Response response = call.execute();

    assertThat(response.code(), equalTo(200));
}

5. Asynchronous GET With OkHttp

To make an asynchronous GET, we need to enqueue a Call. A Callback allows us to read the response when it’s readable. This happens after the response headers are ready.

Reading the response body may still block. OkHttp doesn’t currently offer any asynchronous APIs to receive a response body in parts:

@Test
public void whenAsynchronousGetRequest_thenCorrect() {
    Request request = new Request.Builder()
      .url(BASE_URL + "/date")
      .build();

    Call call = client.newCall(request);
    call.enqueue(new Callback() {
        public void onResponse(Call call, Response response) 
          throws IOException {
            // ...
        }
        
        public void onFailure(Call call, IOException e) {
            fail();
        }
    });
}

6. GET With Query Parameters

Finally, to add query parameters to our GET request, we can take advantage of the HttpUrl.Builder.

After we build the URL, we can pass it to our Request object:

@Test
public void whenGetRequestWithQueryParameter_thenCorrect() 
  throws IOException {
    
    HttpUrl.Builder urlBuilder 
      = HttpUrl.parse(BASE_URL + "/ex/bars").newBuilder();
    urlBuilder.addQueryParameter("id", "1");

    String url = urlBuilder.build().toString();

    Request request = new Request.Builder()
      .url(url)
      .build();
    Call call = client.newCall(request);
    Response response = call.execute();

    assertThat(response.code(), equalTo(200));
}

7. Fetching Response Body

Now that we know how to make a GET request, let’s explore how to read the response body:

@Test
public void whenResponseBodyReadOnce_thenOk() throws IOException {
    OkHttpClient client = new OkHttpClient.Builder().build();

    Request request = new Request.Builder().url(BASE_URL + "/date") 
      .build();

    try (Response response = client.newCall(request).execute()) {
        String first = response.body().string();
        assertNotNull(first);
    }
}

In the code above, we retrieve the response body by invoking the body() method on the Response object and then converting it to a string using the string() method. Importantly, the string() method can only be called once on the same Response object.

If we try to read the body a second time, an IllegalStateException is thrown:

@Test(expected = IllegalStateException.class)
public void whenResponseBodyReadTwice_thenThrows() throws IOException {
    OkHttpClient client = new OkHttpClient.Builder().build();

    Request request = new Request.Builder().url(BASE_URL + "/date")
      .build();

    try (Response response = client.newCall(request).execute()) {
        String first = response.body().string();
        assertNotNull(first);
            
        String second = response.body().string(); // throws IllegalStateException
    }
}

Here, when the body is first consumed, OkHttp consumes and closes the input stream. Any subsequent read attempts have no remaining data to access. In a scenario where we need to reuse the response data, we can store it in a variable and reuse that value instead of calling the string() method again.

8. POST Request 

Now let’s look at a simple POST request where we build a RequestBody to send the parameters “username” and “password”:

@Test
public void whenSendPostRequest_thenCorrect() 
  throws IOException {
    RequestBody formBody = new FormBody.Builder()
      .add("username", "test")
      .add("password", "test")
      .build();

    Request request = new Request.Builder()
      .url(BASE_URL + "/users")
      .post(formBody)
      .build();

    Call call = client.newCall(request);
    Response response = call.execute();
    
    assertThat(response.code(), equalTo(200));
}

Our article, A Quick Guide to Post Requests with OkHttp, has more examples of POST requests with OkHttp.

9. File Uploading

9.1. Upload a File

In this example, we’ll demonstrate how to upload a File. We’ll upload the “test.ext” file using MultipartBody.Builder:

@Test
public void whenUploadFile_thenCorrect() throws IOException {
    RequestBody requestBody = new MultipartBody.Builder()
      .setType(MultipartBody.FORM)
      .addFormDataPart("file", "file.txt",
        RequestBody.create(MediaType.parse("application/octet-stream"), 
          new File("src/test/resources/test.txt")))
      .build();

    Request request = new Request.Builder()
      .url(BASE_URL + "/users/upload")
      .post(requestBody)
      .build();

    Call call = client.newCall(request);
    Response response = call.execute();

    assertThat(response.code(), equalTo(200));
}

9.2. Get File Upload Progress

Then we’ll learn how to get the progress of a File upload. We’ll extend RequestBody to gain visibility into the upload process.

Here’s the upload method:

@Test
public void whenGetUploadFileProgress_thenCorrect() 
  throws IOException {
    RequestBody requestBody = new MultipartBody.Builder()
      .setType(MultipartBody.FORM)
      .addFormDataPart("file", "file.txt",
        RequestBody.create(MediaType.parse("application/octet-stream"), 
          new File("src/test/resources/test.txt")))
      .build();
      
    ProgressRequestWrapper.ProgressListener listener 
      = (bytesWritten, contentLength) -> {
        float percentage = 100f * bytesWritten / contentLength;
        assertFalse(Float.compare(percentage, 100) > 0);
    };

    ProgressRequestWrapper countingBody
      = new ProgressRequestWrapper(requestBody, listener);

    Request request = new Request.Builder()
      .url(BASE_URL + "/users/upload")
      .post(countingBody)
      .build();

    Call call = client.newCall(request);
    Response response = call.execute();

    assertThat(response.code(), equalTo(200));
}

Now here’s the interface ProgressListener, which enables us to observe the upload progress:

public interface ProgressListener {
    void onRequestProgress(long bytesWritten, long contentLength);
}

Next is the ProgressRequestWrapper, which is the extended version of RequestBody:

public class ProgressRequestWrapper extends RequestBody {

    @Override
    public void writeTo(BufferedSink sink) throws IOException {
        BufferedSink bufferedSink;

        countingSink = new CountingSink(sink);
        bufferedSink = Okio.buffer(countingSink);

        delegate.writeTo(bufferedSink);

        bufferedSink.flush();
    }
}

Finally, here’s the CountingSink, which is the extended version of ForwardingSink :

protected class CountingSink extends ForwardingSink {

    private long bytesWritten = 0;

    public CountingSink(Sink delegate) {
        super(delegate);
    }

    @Override
    public void write(Buffer source, long byteCount)
      throws IOException {
        super.write(source, byteCount);
        
        bytesWritten += byteCount;
        listener.onRequestProgress(bytesWritten, contentLength());
    }
}

Note that:

• When extending ForwardingSink to “CountingSink,” we’re overriding the write() method to count the written (transferred) bytes
• When extending RequestBody to “ProgressRequestWrapper,” we’re overriding the writeTo() method to use our “ForwardingSink”

10. Setting a Custom Header

10.1. Setting a Header on a Request

To set any custom header on a Request, we can use a simple addHeader call:

@Test
public void whenSetHeader_thenCorrect() throws IOException {
    Request request = new Request.Builder()
      .url(SAMPLE_URL)
      .addHeader("Content-Type", "application/json")
      .build();

    Call call = client.newCall(request);
    Response response = call.execute();
    response.close();
}

10.2. Setting a Default Header

In this example, we’ll see how to configure a default header on the Client itself, instead of setting it on each and every request.

For example, if we want to set a content type “application/json” for every request, we need to set an interceptor for our client:

@Test
public void whenSetDefaultHeader_thenCorrect() 
  throws IOException {
    
    OkHttpClient client = new OkHttpClient.Builder()
      .addInterceptor(
        new DefaultContentTypeInterceptor("application/json"))
      .build();

    Request request = new Request.Builder()
      .url(SAMPLE_URL)
      .build();

    Call call = client.newCall(request);
    Response response = call.execute();
    response.close();
}

Here’s the DefaultContentTypeInterceptor, which is the extended version of Interceptor:

public class DefaultContentTypeInterceptor implements Interceptor {
    
    public Response intercept(Interceptor.Chain chain) 
      throws IOException {

        Request originalRequest = chain.request();
        Request requestWithUserAgent = originalRequest
          .newBuilder()
          .header("Content-Type", contentType)
          .build();

        return chain.proceed(requestWithUserAgent);
    }
}

Note that the interceptor adds the header to the original request.

11. Do Not Follow Redirects

In this example, we’ll see how to configure the OkHttpClient to stop following redirects.

By default, if a GET request is answered with an HTTP 301 Moved Permanently, the redirect is automatically followed. In some use cases, that’s perfectly fine, but there are other use cases where it’s not desired.

To achieve this behavior, when we build our client, we need to set followRedirects to false.

Note that the response will return an HTTP 301 status code:

@Test
public void whenSetFollowRedirects_thenNotRedirected() 
  throws IOException {

    OkHttpClient client = new OkHttpClient().newBuilder()
      .followRedirects(false)
      .build();
    
    Request request = new Request.Builder()
      .url("http://t.co/I5YYd9tddw")
      .build();

    Call call = client.newCall(request);
    Response response = call.execute();

    assertThat(response.code(), equalTo(301));
}

If we turn on the redirect with a true parameter (or remove it completely), the client will follow the redirection, and the test will fail, as the return code will be an HTTP 200.

12. Timeouts

We can use timeouts to fail a call when its peer is unreachable. Network failures can be due to client connectivity problems, server availability problems, or anything in between. OkHttp supports connect, read, and write timeouts.

In this example, we configured our client with a 1-second read timeout, while the server responds with a 2-second delay:

@Test
public void whenSetRequestTimeout_thenFail() 
  throws IOException {
    OkHttpClient client = new OkHttpClient.Builder()
      .readTimeout(1, TimeUnit.SECONDS)
      .build();

    Request request = new Request.Builder()
      .url(BASE_URL + "/delay/2")
      .build();
 
    Call call = client.newCall(request);
    Response response = call.execute();

    assertThat(response.code(), equalTo(200));
}

Note that the test will fail, as the client timeout is lower than the resource response time.

13. Canceling a Call

We can use Call.cancel() to stop an ongoing call immediately. If a thread is currently writing a request or reading a response, an IOException will be thrown.

We use this method to conserve the network when a call is no longer necessary, like when our user navigates away from an application:

@Test(expected = IOException.class)
public void whenCancelRequest_thenCorrect() 
  throws IOException {
    ScheduledExecutorService executor
      = Executors.newScheduledThreadPool(1);

    Request request = new Request.Builder()
      .url(BASE_URL + "/delay/2")  
      .build();

    int seconds = 1;
    long startNanos = System.nanoTime();

    Call call = client.newCall(request);

    executor.schedule(() -> {
        logger.debug("Canceling call: "  
            + (System.nanoTime() - startNanos) / 1e9f);

        call.cancel();
            
        logger.debug("Canceled call: " 
            + (System.nanoTime() - startNanos) / 1e9f);
        
    }, seconds, TimeUnit.SECONDS);

    logger.debug("Executing call: " 
      + (System.nanoTime() - startNanos) / 1e9f);

    Response response = call.execute();
	
    logger.debug(Call was expected to fail, but completed: " 
      + (System.nanoTime() - startNanos) / 1e9f, response);
}

14. Response Caching

To create a Cache, we’ll need a cache directory that we can read and write to, and a limit on the cache’s size.

The client will use it to cache the response:

@Test
public void  whenSetResponseCache_thenCorrect() 
  throws IOException {
    int cacheSize = 10 * 1024 * 1024;

    File cacheDirectory = new File("src/test/resources/cache");
    Cache cache = new Cache(cacheDirectory, cacheSize);

    OkHttpClient client = new OkHttpClient.Builder()
      .cache(cache)
      .build();

    Request request = new Request.Builder()
      .url("http://publicobject.com/helloworld.txt")
      .build();

    Response response1 = client.newCall(request).execute();
    logResponse(response1);

    Response response2 = client.newCall(request).execute();
    logResponse(response2);
}

After launching the test, the response from the first call won’t be cached. A call to the method cacheResponse will return null, while a call to the method networkResponse will return the response from the network.

The cache folder will also be filled with the cache files.

The second call execution will produce the opposite effect, as the response will already be cached. This means that a call to networkResponse will return null, while a call to cacheResponse will return the response from the cache.

To prevent a response from using the cache, we can use CacheControl.FORCE_NETWORK. To prevent it from using the network, we can use CacheControl.FORCE_CACHE.

It’s important to note that if we use FORCE_CACHE, and the response requires the network, OkHttp will return a 504 Unsatisfiable Request response.

15. Conclusion

In this article, we explored several examples of how to use OkHttp as an HTTP & HTTP/2 client.