blob: ecc7c691361f09c6d5abd2daab7dbe72e32f38bd [file] [log] [blame]
Narayan Kamath166772b2013-11-04 16:04:55 +00001<!DOCTYPE html>
2<html lang="en">
3 <head>
4 <meta charset="utf-8">
5 <title>OkHttp</title>
6 <meta name="viewport" content="width=device-width, initial-scale=1.0">
7 <meta name="description" content="An HTTP &amp; SPDY client for Android and Java applications">
8 <link href="static/bootstrap-combined.min.css" rel="stylesheet">
9 <link href="static/app.css" rel="stylesheet">
10 <link href="static/app-theme.css" rel="stylesheet">
11 <link href="http://fonts.googleapis.com/css?family=Roboto:400,300italic,100,100italic,300" rel="stylesheet" type="text/css">
12 <!--[if lt IE 9]><script src="static/html5shiv.min.js"></script><![endif]-->
13 </head>
14 <body data-target=".content-nav">
15 <header>
16 <div class="container">
17 <div class="row">
18 <div class="span5">
19 <h1>OkHttp</h1>
20 </div>
21 <div class="span7">
22 <menu>
23 <ul>
24 <li><a href="#download" class="menu download">Download <span class="version-tag">Latest</span></a></li>
25 <li><a href="http://github.com/square/okhttp" data-title="View GitHub Project" class="menu github"><img src="static/icon-github.png" alt="GitHub"/></a></li>
26 <li><a href="http://square.github.io/" data-title="Square Open Source Portal" class="menu square"><img src="static/icon-square.png" alt="Square"/></a></li>
27 </ul>
28 </menu>
29 </div>
30 </div>
31 </header>
32 <section id="subtitle">
33 <div class="container">
34 <div class="row">
35 <div class="span12">
36 <h2>An <strong>HTTP &amp; SPDY</strong> client for Android and Java applications</h2>
37 </div>
38 </div>
39 </div>
40 </section>
41 <section id="body">
42 <div class="container">
43 <div class="row">
44 <div class="span9">
45 <h3 id="overview">Overview</h3>
Neil Fullere78f1172015-01-20 09:39:41 +000046 <p>HTTP is the way modern applications network. It’s how we exchange data &amp; media.
Narayan Kamath166772b2013-11-04 16:04:55 +000047 Doing HTTP efficiently makes your stuff load faster and saves bandwidth.</p>
48
49 <p>OkHttp is an HTTP client that’s efficient by default:</p>
50 <ul>
Neil Fullere78f1172015-01-20 09:39:41 +000051 <li>HTTP/2 and SPDY support allows all requests to the same host to share a socket.</li>
Narayan Kamath166772b2013-11-04 16:04:55 +000052 <li>Connection pooling reduces request latency (if SPDY isn’t available).</li>
53 <li>Transparent GZIP shrinks download sizes.</li>
54 <li>Response caching avoids the network completely for repeat requests.</li>
55 </ul>
56
57 <p>OkHttp perseveres when the network is troublesome: it will silently recover from
58 common connection problems. If your service has multiple IP addresses OkHttp will
59 attempt alternate addresses if the first connect fails. This is necessary for IPv4+IPv6
Neil Fullere78f1172015-01-20 09:39:41 +000060 and for services hosted in redundant data centers. OkHttp initiates new connections
61 with modern TLS features (SNI, ALPN), and falls back to TLS 1.0 if the handshake
62 fails.</p>
Narayan Kamath166772b2013-11-04 16:04:55 +000063
Neil Fullere78f1172015-01-20 09:39:41 +000064 <p>Using OkHttp is easy. Its 2.0 API is designed with fluent builders and
65 immutability. It supports both synchronous blocking calls and async calls with
66 callbacks.</p>
Narayan Kamath166772b2013-11-04 16:04:55 +000067
Neil Fullere78f1172015-01-20 09:39:41 +000068 <p>You can try out OkHttp without rewriting your network code. The
69 <code>okhttp-urlconnection</code> module implements the familiar
70 <code>java.net.HttpURLConnection</code> API and the <code>okhttp-apache</code>
71 module implements the Apache <code>HttpClient</code> API.</p>
72
73 <p>OkHttp supports Android 2.3 and above. For Java, the minimum requirement is 1.7.</p>
Narayan Kamath166772b2013-11-04 16:04:55 +000074
75 <h3 id="examples">Examples</h3>
76 <h4>Get a URL</h4>
77 <p>This program downloads a URL and print its contents as a string. <a href="https://raw.github.com/square/okhttp/master/samples/guide/src/main/java/com/squareup/okhttp/guide/GetExample.java">Full source</a>.
78<pre class="prettyprint">
Neil Fullere78f1172015-01-20 09:39:41 +000079OkHttpClient client = new OkHttpClient();
Narayan Kamath166772b2013-11-04 16:04:55 +000080
Neil Fullere78f1172015-01-20 09:39:41 +000081String run(String url) throws IOException {
82 Request request = new Request.Builder()
83 .url(url)
84 .build();
85
86 Response response = client.newCall(request).execute();
87 return response.body().string();
88}
Narayan Kamath166772b2013-11-04 16:04:55 +000089</pre>
90 <h4>Post to a Server</h4>
91 <p>This program posts data to a service. <a href="https://raw.github.com/square/okhttp/master/samples/guide/src/main/java/com/squareup/okhttp/guide/PostExample.java">Full source</a>.
92
93<pre class="prettyprint">
Neil Fullere78f1172015-01-20 09:39:41 +000094public static final MediaType JSON
95 = MediaType.parse("application/json; charset=utf-8");
Narayan Kamath166772b2013-11-04 16:04:55 +000096
Neil Fullere78f1172015-01-20 09:39:41 +000097OkHttpClient client = new OkHttpClient();
Narayan Kamath166772b2013-11-04 16:04:55 +000098
Neil Fullere78f1172015-01-20 09:39:41 +000099String post(String url, String json) throws IOException {
100 RequestBody body = RequestBody.create(JSON, json);
101 Request request = new Request.Builder()
102 .url(url)
103 .post(body)
104 .build();
105 Response response = client.newCall(request).execute();
106 return response.body().string();
107}
Narayan Kamath166772b2013-11-04 16:04:55 +0000108</pre>
109
Narayan Kamath166772b2013-11-04 16:04:55 +0000110 <h3 id="download">Download</h3>
Neil Fullere78f1172015-01-20 09:39:41 +0000111 <p><a href="https://search.maven.org/remote_content?g=com.squareup.okhttp&a=okhttp&v=LATEST" class="dl version-href">&darr; <span class="version-tag">Latest</span> JAR</a></p>
112 <p>You'll also need <a href="http://github.com/square/okio">Okio</a>, which OkHttp
113 uses for fast I/O and resizable buffers. Download the
114 <a href="https://search.maven.org/remote_content?g=com.squareup.okio&a=okio&v=LATEST">latest JAR</a>.
115 <p>The source code to OkHttp, its samples, and this website is <a href="http://github.com/square/okhttp">available on GitHub</a>.</p>
Narayan Kamath166772b2013-11-04 16:04:55 +0000116
117 <h4>Maven</h4>
118 <pre class="prettyprint">&lt;dependency>
119 &lt;groupId>com.squareup.okhttp&lt;/groupId>
120 &lt;artifactId>okhttp&lt;/artifactId>
121 &lt;version><span class="version pln"><em>(insert latest version)</em></span>&lt;/version>
122&lt;/dependency></pre>
123
Neil Fullera2cab722015-04-13 13:06:22 +0100124 <h4>Gradle</h4>
125 <pre class="prettyprint">compile 'com.squareup.okhttp:okhttp:<span class="version pln"><em>(insert latest version)</em></span>'</pre>
126
Narayan Kamath166772b2013-11-04 16:04:55 +0000127 <h3 id="contributing">Contributing</h3>
128 <p>If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request.</p>
129 <p>When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also make sure your code compiles by running <code>mvn clean verify</code>.</p>
130 <p>Before your code can be accepted into the project you must also sign the <a href="http://squ.re/sign-the-cla">Individual Contributor License Agreement (CLA)</a>.</p>
131
132 <h3 id="license">License</h3>
Neil Fullere78f1172015-01-20 09:39:41 +0000133 <pre>Copyright 2014 Square, Inc.
Narayan Kamath166772b2013-11-04 16:04:55 +0000134
135Licensed under the Apache License, Version 2.0 (the "License");
136you may not use this file except in compliance with the License.
137You may obtain a copy of the License at
138
139 http://www.apache.org/licenses/LICENSE-2.0
140
141Unless required by applicable law or agreed to in writing, software
142distributed under the License is distributed on an "AS IS" BASIS,
143WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
144See the License for the specific language governing permissions and
145limitations under the License.</pre>
146 </div>
147 <div class="span3">
148 <div class="content-nav" data-spy="affix" data-offset-top="80">
149 <ul class="nav nav-tabs nav-stacked primary">
150 <li><a href="#overview">Overview</a></li>
151 <li><a href="#examples">Examples</a></li>
152 <li><a href="#download">Download</a></li>
153 <li><a href="#contributing">Contributing</a></li>
154 <li><a href="#license">License</a></li>
155 </ul>
156 <ul class="nav nav-pills nav-stacked secondary">
Neil Fullere78f1172015-01-20 09:39:41 +0000157 <li><a href="https://github.com/square/okhttp/wiki">Wiki</a></li>
Tobias Thierer6c251e22016-06-24 19:04:17 +0100158 <li><a href="2.x/okhttp/">Javadoc</a></li>
Neil Fuller3c938a32014-02-19 09:40:26 +0000159 <li><a href="http://stackoverflow.com/questions/tagged/okhttp?sort=active">StackOverflow</a></li>
Narayan Kamath166772b2013-11-04 16:04:55 +0000160 </ul>
161 </div>
162 </div>
163 </div>
164 <div class="row">
165 <div class="span12 logo">
166 <a href="https://squareup.com"><img src="static/logo-square.png" alt="Square, Inc."/></a>
167 </div>
168 </div>
169 </div>
170 </section>
171 <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
172 <script src="static/bootstrap.min.js"></script>
173 <script src="static/jquery.smooth-scroll.min.js"></script>
174 <script src="static/jquery-maven-artifact.min.js"></script>
175 <script src="static/prettify.js"></script>
176 <script type="text/javascript">
177 $(function() {
178 // Syntax highlight code blocks.
179 prettyPrint();
180
181 // Spy on scroll position for real-time updating of current section.
182 $('body').scrollspy();
183
184 // Use smooth-scroll for internal links.
185 $('a').smoothScroll();
186
187 // Enable tooltips on the header nav image items.
188 $('.menu').tooltip({
189 placement: 'bottom',
190 trigger: 'hover',
191 container: 'body',
192 delay: {
193 show: 500,
194 hide: 0
195 }
196 });
197
198 // Look up the latest version of the library.
199 $.fn.artifactVersion({
200 'groupId': 'com.squareup.okhttp',
Neil Fullerc6bd6832014-03-14 16:02:10 +0000201 'artifactId': 'okhttp'
Narayan Kamath166772b2013-11-04 16:04:55 +0000202 }, function(version, url) {
203 $('.version').text(version);
204 $('.version-tag').text('v' + version);
205 $('.version-href').attr('href', url);
206 });
207 });
208
209 var _gaq = _gaq || [];
210 _gaq.push(['_setAccount', 'UA-40704740-2']);
211 _gaq.push(['_trackPageview']);
212
213 (function() {
214 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
215 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
216 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
217 })();
218 </script>
219 </body>
220</html>