0
# OkHttp
1

2
OkHttp is a high-performance HTTP client library for Android and Java applications that provides comprehensive support for HTTP/1.1, HTTP/2, and SPDY protocols. The library offers a modern, fluent API for making HTTP requests with features including automatic request/response compression, connection pooling, transparent GZIP support, response caching, and seamless handling of common authentication schemes.
3

4
## Package Information
5

6
- **Package Name**: com.squareup.okhttp:okhttp
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 2.7.5
10
- **License**: Apache-2.0
11
- **Installation**: Add dependency to Maven `pom.xml` or Gradle `build.gradle`
12

13
Maven:
14
```xml
15
<dependency>
16
    <groupId>com.squareup.okhttp</groupId>
17
    <artifactId>okhttp</artifactId>
18
    <version>2.7.5</version>
19
</dependency>
20
```
21

22
Gradle:
23
```gradle
24
implementation 'com.squareup.okhttp:okhttp:2.7.5'
25
```
26

27
## Core Imports
28

29
```java
30
import com.squareup.okhttp.OkHttpClient;
31
import com.squareup.okhttp.Request;
32
import com.squareup.okhttp.Response;
33
import com.squareup.okhttp.Call;
34
import com.squareup.okhttp.Callback;
35
```
36

37
## Basic Usage
38

39
```java
40
import com.squareup.okhttp.OkHttpClient;
41
import com.squareup.okhttp.Request;
42
import com.squareup.okhttp.Response;
43
import java.io.IOException;
44

45
// Create client
46
OkHttpClient client = new OkHttpClient();
47

48
// Build request
49
Request request = new Request.Builder()
50
    .url("https://api.example.com/data")
51
    .build();
52

53
// Execute synchronously
54
Response response = client.newCall(request).execute();
55
try {
56
    if (response.isSuccessful()) {
57
        String responseBody = response.body().string();
58
        System.out.println(responseBody);
59
    }
60
} finally {
61
    response.body().close();
62
}
63

64
// Execute asynchronously
65
client.newCall(request).enqueue(new Callback() {
66
    @Override
67
    public void onFailure(Request request, IOException e) {
68
        e.printStackTrace();
69
    }
70

71
    @Override
72
    public void onResponse(Response response) throws IOException {
73
        try {
74
            if (response.isSuccessful()) {
75
                String responseBody = response.body().string();
76
                System.out.println(responseBody);
77
            }
78
        } finally {
79
            response.body().close();
80
        }
81
    }
82
});
83
```
84

85
## Architecture
86

87
OkHttp is built around several key components:
88

89
- **OkHttpClient**: Central configuration point and factory for HTTP calls
90
- **Request/Response**: Immutable objects representing HTTP requests and responses
91
- **Call**: Represents a single HTTP request/response exchange that can be executed
92
- **Connection Pool**: Manages HTTP/HTTPS connection reuse for efficiency
93
- **Interceptors**: Application and network-level request/response processing
94
- **Cache**: Optional HTTP response caching with configurable storage
95
- **Authentication**: Pluggable authentication handling for various schemes
96

97
## Capabilities
98

99
### HTTP Client Configuration
100

101
Central client configuration with support for timeouts, proxies, SSL settings, authentication, and connection pooling.
102

103
```java { .api }
104
public class OkHttpClient implements Cloneable {
105
    public OkHttpClient();
106
    public Call newCall(Request request);
107
    public OkHttpClient clone();
108
}
109
```
110

111
[HTTP Client Configuration](./http-client.md)
112

113
### Request Building
114

115
Fluent API for building HTTP requests with URLs, methods, headers, and request bodies.
116

117
```java { .api }
118
public final class Request {
119
    public static class Builder {
120
        public Builder();
121
        public Builder url(String url);
122
        public Builder url(HttpUrl url);
123
        public Builder header(String name, String value);
124
        public Builder addHeader(String name, String value);
125
        public Builder get();
126
        public Builder post(RequestBody body);
127
        public Builder put(RequestBody body);
128
        public Builder delete();
129
        public Builder method(String method, RequestBody body);
130
        public Request build();
131
    }
132
}
133
```
134

135
[Request Building](./request-building.md)
136

137
### Response Handling
138

139
Comprehensive response handling with status codes, headers, and multiple body access methods.
140

141
```java { .api }
142
public final class Response {
143
    public int code();
144
    public boolean isSuccessful();
145
    public String message();
146
    public Headers headers();
147
    public ResponseBody body();
148
    public Protocol protocol();
149
    public Request request();
150
}
151
```
152

153
[Response Handling](./response-handling.md)
154

155
### Request and Response Bodies
156

157
Support for various content types with efficient streaming and multiple access patterns.
158

159
```java { .api }
160
public abstract class RequestBody {
161
    public static RequestBody create(MediaType contentType, String content);
162
    public static RequestBody create(MediaType contentType, byte[] content);
163
    public static RequestBody create(MediaType contentType, File file);
164
    public abstract MediaType contentType();
165
    public abstract void writeTo(BufferedSink sink) throws IOException;
166
}
167

168
public abstract class ResponseBody {
169
    public abstract MediaType contentType();
170
    public abstract long contentLength() throws IOException;
171
    public final String string() throws IOException;
172
    public final byte[] bytes() throws IOException;
173
    public final InputStream byteStream() throws IOException;
174
}
175
```
176

177
[Request and Response Bodies](./request-response-bodies.md)
178

179
### Form Data and Multipart
180

181
Builders for HTML form encoding and multipart form data with file upload support.
182

183
```java { .api }
184
public final class FormEncodingBuilder {
185
    public FormEncodingBuilder();
186
    public FormEncodingBuilder add(String name, String value);
187
    public FormEncodingBuilder addEncoded(String name, String value);
188
    public RequestBody build();
189
}
190

191
public final class MultipartBuilder {
192
    public MultipartBuilder();
193
    public MultipartBuilder type(MediaType type);
194
    public MultipartBuilder addFormDataPart(String name, String value);
195
    public MultipartBuilder addFormDataPart(String name, String filename, RequestBody value);
196
    public RequestBody build();
197
}
198
```
199

200
[Form Data and Multipart](./form-data-multipart.md)
201

202
### HTTP Utilities
203

204
URL handling, header management, media type parsing, and HTTP protocol utilities.
205

206
```java { .api }
207
public final class HttpUrl {
208
    public static HttpUrl parse(String url);
209
    public String scheme();
210
    public String host();
211
    public int port();
212
    public String encodedPath();
213
    public String queryParameter(String name);
214
    public static class Builder {
215
        public Builder scheme(String scheme);
216
        public Builder host(String host);
217
        public Builder port(int port);
218
        public Builder encodedPath(String encodedPath);
219
        public Builder addQueryParameter(String name, String value);
220
        public HttpUrl build();
221
    }
222
}
223
```
224

225
[HTTP Utilities](./http-utilities.md)
226

227
### Caching
228

229
HTTP response caching with filesystem storage, cache control directives, and LRU eviction.
230

231
```java { .api }
232
public final class Cache {
233
    public Cache(File directory, long maxSize);
234
    public void evictAll() throws IOException;
235
    public long getSize() throws IOException;
236
    public int getHitCount();
237
    public int getNetworkCount();
238
}
239

240
public final class CacheControl {
241
    public static final CacheControl FORCE_NETWORK;
242
    public static final CacheControl FORCE_CACHE;
243
    public boolean noCache();
244
    public boolean noStore();
245
    public int maxAgeSeconds();
246
    public static CacheControl parse(Headers headers);
247
}
248
```
249

250
[Caching](./caching.md)
251

252
### Connection Management
253

254
Connection pooling, SSL/TLS configuration, and connection specifications for performance optimization.
255

256
```java { .api }
257
public final class ConnectionPool {
258
    public ConnectionPool(int maxIdleConnections, long keepAliveDurationMs);
259
    public int getIdleConnectionCount();
260
    public int getConnectionCount();
261
    public void evictAll();
262
}
263

264
public final class ConnectionSpec {
265
    public static final ConnectionSpec MODERN_TLS;
266
    public static final ConnectionSpec COMPATIBLE_TLS;
267
    public static final ConnectionSpec CLEARTEXT;
268
    public boolean isTls();
269
    public List<CipherSuite> cipherSuites();
270
    public List<TlsVersion> tlsVersions();
271
}
272
```
273

274
[Connection Management](./connection-management.md)
275

276
### Authentication and Security
277

278
Authentication handling, certificate pinning, TLS handshake management, and credential utilities.
279

280
```java { .api }
281
public interface Authenticator {
282
    Request authenticate(Proxy proxy, Response response) throws IOException;
283
    Request authenticateProxy(Proxy proxy, Response response) throws IOException;
284
}
285

286
public final class CertificatePinner {
287
    public static final CertificatePinner DEFAULT;
288
    public void check(String hostname, List<Certificate> peerCertificates) 
289
        throws SSLPeerUnverifiedException;
290
    public static String pin(Certificate certificate);
291
}
292

293
public final class Credentials {
294
    public static String basic(String userName, String password);
295
}
296
```
297

298
[Authentication and Security](./authentication-security.md)
299

300
### Interceptors
301

302
Request and response interception for logging, authentication, caching, and custom processing.
303

304
```java { .api }
305
public interface Interceptor {
306
    Response intercept(Chain chain) throws IOException;
307
    
308
    interface Chain {
309
        Request request();
310
        Response proceed(Request request) throws IOException;
311
        Connection connection();
312
    }
313
}
314
```
315

316
[Interceptors](./interceptors.md)
317

318
### Asynchronous Execution
319

320
Callback-based asynchronous execution with dispatcher configuration and call management.
321

322
```java { .api }
323
public interface Callback {
324
    void onFailure(Request request, IOException e);
325
    void onResponse(Response response) throws IOException;
326
}
327

328
public final class Dispatcher {
329
    public Dispatcher();
330
    public void setMaxRequests(int maxRequests);
331
    public void setMaxRequestsPerHost(int maxRequestsPerHost);
332
    public void cancel(Object tag);
333
    public int getRunningCallCount();
334
    public int getQueuedCallCount();
335
}
336
```
337

338
[Asynchronous Execution](./async-execution.md)
339

340
## Common Types
341

342
```java { .api }
343
public final class Headers {
344
    public static Headers of(String... namesAndValues);
345
    public static Headers of(Map<String, String> headers);
346
    public String get(String name);
347
    public Date getDate(String name);
348
    public List<String> values(String name);
349
    public Set<String> names();
350
    public int size();
351
    public String name(int index);
352
    public String value(int index);
353
    public Builder newBuilder();
354
    public Map<String, List<String>> toMultimap();
355
    
356
    public static class Builder {
357
        public Builder add(String name, String value);
358
        public Builder set(String name, String value);
359
        public Builder removeAll(String name);
360
        public Headers build();
361
    }
362
}
363

364
public final class MediaType {
365
    public static MediaType parse(String string);
366
    public String type();
367
    public String subtype();
368
    public Charset charset();
369
    public Charset charset(Charset defaultValue);
370
}
371

372
public enum Protocol {
373
    HTTP_1_0("http/1.0"), HTTP_1_1("http/1.1"), SPDY_3("spdy/3.1"), HTTP_2("h2");
374
    public static Protocol get(String protocol) throws IOException;
375
}
376

377
public enum TlsVersion {
378
    TLS_1_2("TLSv1.2"), TLS_1_1("TLSv1.1"), TLS_1_0("TLSv1"), SSL_3_0("SSLv3");
379
}
380

381
public final class Call {
382
    public Response execute() throws IOException;
383
    public void enqueue(Callback responseCallback);
384
    public void cancel();
385
    public boolean isExecuted();
386
    public boolean isCanceled();
387
}
388

389
public final class Challenge {
390
    public String scheme();
391
    public String realm();
392
    public Map<String, String> authParams();
393
}
394

395
public final class Handshake {
396
    public TlsVersion tlsVersion();
397
    public CipherSuite cipherSuite();
398
    public List<Certificate> peerCertificates();
399
    public List<Certificate> localCertificates();
400
}
401

402
public enum CipherSuite {
403
    // TLS 1.2 cipher suites
404
    TLS_RSA_WITH_AES_128_CBC_SHA("TLS_RSA_WITH_AES_128_CBC_SHA"),
405
    TLS_RSA_WITH_AES_256_CBC_SHA("TLS_RSA_WITH_AES_256_CBC_SHA"),
406
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256("TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"),
407
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384("TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384");
408
    // Additional cipher suites available - over 150 constants supported
409
}
410
```