OkHttp 2.0

Square’s HTTP client for Android and Java has a new API.

Square Engineering
Jun 23, 2014 · 3 min read

Written by Jesse Wilson.

Heads up, we’ve moved! If you’d like to continue keeping up with the latest technical content from Square please visit us at our new home https://developer.squareup.com/blog

OkHttp started as a fork of Android’s HttpURLConnection. That gave us a solid foundation to build upon. Working behind a widely-used API meant that upgrading from AOSP’s HttpURLConnection to ours was easy: just configure URLs stream handler factory.

But we’ve outgrown the HttpURLConnection API. Its fully-synchronous API means that application code needs to manage how requests are dispatched. Requests and responses are together in one class which makes certain operations awkward or inefficient. Most painfully, we’re limited in what we can expose: Was my request redirected? Did the response come from a cache? OkHttp knows the answers to these questions but the HttpURLConnection API offers no way for you to ask them.

Request, Response, and Call

With 2.0, OkHttp introduces three fundamental types: Request, Response, and Call. A call executes a request to produce a response. You can do that synchronously with a blocking call:

Or asynchronously with a callback:

A Request’s Journey

Above we complained that HttpURLConnection lacks APIs to ask how a response was reached. With redirects and caching, that journey can be interesting! One handy example is what happens when OkHttp downloads its own jar file from Maven Central.

Following Redirects

First we’re redirected from the HTTP to the HTTPS site:

Next we’re redirected from the LATEST tag to the specific file we want.

Finally we download the file. The response includes headers to make caching possible.

OkHttp exposes these redirects with Response.priorResponse(). If you’re redirected multiple times, you will have a chain of prior responses. These will be returned in order from last-to-first; reverse them for chronological order:

Cache and Network Responses

If we re-download the same URL, OkHttp’s response cache may kick in. Responseoffers two methods to check where a response came from: cacheResponse() and networkResponse(). Note that for conditional gets, both will be present!

When downloading a jar file from Maven Central, Response.cacheResponse()returns the cached response from above:

This cached response required validation from the server. OkHttp needed to ask, “Has the cached value changed?” Checking Response.networkResponse() confirms that it had not:

Prior responses from redirects also support cacheResponse() and networkResponse(). Use this to interrogate whether any part of a response used the network.

Upgrading to OkHttp 2.0

OkHttp 2.0 is not backwards-compatible. The changelog describes what’s changed and what’s gone. For example, to continue using the HttpURLConnection API, you will need the optional okhttp-urlconnection dependency. To make upgrading easier, we’ve also released OkHttp 1.6 which is the 1.5 code plus some new 2.0 APIs. Use 1.6 to transition to 2.x APIs.

Get OkHttp from Maven or download it from the project website. Read more code examples in the project’s Recipes doc.


Square Corner Blog

Buying and selling sound like simple things - and they…

Square Engineering

Written by

The official account for @Square Engineering.

Square Corner Blog

Buying and selling sound like simple things - and they should be. Somewhere along the way, they got complicated. At Square, we're working hard to make commerce easy for everyone.

Square Engineering

Written by

The official account for @Square Engineering.

Square Corner Blog

Buying and selling sound like simple things - and they should be. Somewhere along the way, they got complicated. At Square, we're working hard to make commerce easy for everyone.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store