Code and documentation to use okhttp

[candrews]

There's no documentation or code that allows a potential users of okhttp to use it in an Android app or a regular, non-Android program. Such support code and documentation would sure be helpful.

[pforhan]

@swankjesse, would it make sense to drop OkHttpModule in here, or maybe we should have a full-fledged sample app?

[swankjesse]

We should fill out the README with example usage. For now, OkHttpConnection works exactly the same as HttpURLConnection:
URL url = ...
OkHttpConnection httpConnection = OkHttpConnection.open(url);

We'll also need to figure out how to hook up the HTTP response cache and document that. I'm hoping that its API also mirrors Android's built-in response cache. We still need to write the code. I'm hoping the API looks like this:
File httpCacheDir = ...
long httpCacheSize = ...
OkHttpResponseCache.install(httpCacheDir, httpCacheSize);

Also outstanding on our end is to publish OkHttp to maven so end users can get .jar files.

[swankjesse]

@pforhan great idea! We should publish OkHttpClient in its own maven module for folks interested in upgrading from Apache HTTP client.

[sdhull]

FWIW, I'm also interested in some docs & more samples. I'm trying to decide whether to use OkHttp or google-http-client for my android project and I'm really at a loss.

I understand putting together docs & samples isn't really glamorous or exciting, but it would certainly be a great way to encourage usage and engagement by the community.

If (in the meantime) someone has some some pointers for me, I'd very much appreciate that.

[JakeWharton]

We are working on these. Check back next week.

For what it's worth, OkHttpClient is all you need to look at. 99% of everything else is covered by normal HttpUrlConnection and HttpsUrlConnection's APIs.

[sdhull]

@JakeWharton I'm really glad to hear that. Everything seems simple enough for get requests, but I'm a bit unclear on post requests. I was hoping for a simple setContent API or something like that, but from perusing the tests, it seems a bit more involved, eg (with some branches removed):

    HttpURLConnection conn = client.open(server.getUrl("/"));
    conn.setDoOutput(true);  // this is redundant to setting requestMethod right?
    conn.setRequestMethod("POST");
    conn.setFixedLengthStreamingMode(n);
    OutputStream out = conn.getOutputStream();
    byte[] buf = new byte[writeKind == WriteKind.SMALL_BUFFERS ? 256 : 64 * 1024];
    Arrays.fill(buf, (byte) 'x');   // xxxxxxxxxxxxxxxxxxxxxxxxx....
    for (int i = 0; i < n; i += buf.length) {
      out.write(buf, 0, Math.min(buf.length, n - i));
    }
    out.close();

[JakeWharton]

Sending content is a bit more involved, yes. Check back next week :)

[sdhull]

Copy that. I'll try to make do until then. Unfortunately the Downloads page has no deployable jars and we decided to avoid the complexity of Maven setup with our project for now. There's also no simple build option so was wondering what you'd recommend for me to get started.

[sdhull]

Moreover, from searching maven, it seems there isn't even a jar in Maven that can satisfy the dependency (nothing with groupId of "com.squareup" and "okhttp").

I guess figuring out maven isn't so bad, but when trying to maven package to build a jar I can use, tests fail with 63 errors. I can skip tests of course but is that wise? Are the failing tests failing because my environment isn't setup properly or because the project is actually broken? If it's actually broken right now, do you know of the last green SHA?

Sorry about all the questions. I don't want to pull google-http-client into my project only to switch it out for okhttp next week. I guess I was idiotic to start writing code that depends on a library I didn't have in my libs dir yet. 😔

[JakeWharton]

Tests require Java 7. You can safely mvn clean install -DskipTests (or package) for now. We verify them on every pull.

[sdhull]

Awesome! Thanks so much @JakeWharton, I'm very grateful 😄

[jvanzyl]

I have made a couple recent builds for my own work using okhttp which you can use for now:

http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.tesla.okhttp%22%20AND%20a%3A%22okhttp%22

[JakeWharton]

There are a few samples in master and a documentation website that is now live (and will be expanded on).