okhttp3-5-x

# OkHttp 5.x Reference (v5.4.0) OkHttp is an efficient HTTP client by default: HTTP/2 support, connection pooling, transparent GZIP, and response caching. It silently recovers from common connection problems and attempts alternate addresses when the first connect fails. ## Official Documentation Sources All authoritative information is on the official OkHttp site: | Topic | URL | |-------|-----| | **Overview** | https://square.github.io/okhttp/ | | **Calls** | https://square.github.io/okhttp/features/calls/ | | **Caching** | https://square.github.io/okhttp/features/caching/ | | **Connections** | https://square.github.io/okhttp/features/connections/ | | **Events** | https://square.github.io/okhttp/features/events/ | | **HTTPS** | https://square.github.io/okhttp/features/https/ | | **Interceptors** | https://square.github.io/okhttp/features/interceptors/ | | **Recipes** | https://square.github.io/okhttp/recipes/ | | **Security** | https://square.github.io/okhttp/security/ | | **API Javadoc** | https://square.github.io/okhttp/5.x/okhttp/okhttp3/ | | **MockWebServer** | https://square.github.io/okhttp/mockwebserver/ | | **5.x Change Log** | https://square.github.io/okhttp/changelogs/changelog/ | | **Maven Central** | https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp | | **GitHub** | https://github.com/square/okhttp | **RFC Standards followed by OkHttp:** - HTTP Semantics — RFC 9110 - HTTP Caching — RFC 9111 - HTTP/1.1 — RFC 9112 - HTTP/2 — RFC 9113 - WebSockets — RFC 6455 - SSE — Server-sent events - Happy Eyeballs — RFC 6555 ## Capability Boundaries ### ✅ Strong Suits 1. HTTP/2 support — all requests to the same host share a socket 2. Connection pooling — reduces latency, automatic reuse 3. Transparent GZIP — shrinks download sizes automatically 4. Response caching — avoids network for repeat requests 5. Interceptors — monitor, rewrite, and retry calls (Application + Network layers) 6. Fast Fallback (Happy Eyeballs RFC 6555) — concurrent IPv4/IPv6 connection attempts 7. TLS 1.3, ALPN, certificate pinning 8. EventListener API — capture metrics on HTTP calls 9. MockWebServer — test HTTP/HTTPS/HTTP/2 clients 10. GraalVM Native Image support 11. Java 9 Modules support (5.2+) 12. BOM for dependency management ### ⚠️ Requirements 1. Java 8+ or Android 5.0+ (API level 21+) 2. Kotlin Multiplatform: Maven projects must use `okhttp-jvm` artifact (not `okhttp`) 3. Requires Okio and Kotlin stdlib (transitive dependencies) 4. For certificate pinning: server TLS admin coordination required ### ❌ Out of Scope (with alternatives) 1. GET with body — OkHttp does not allow GET with a body (use POST) 2. Custom cache implementations — Cache is not an interface (use interceptors for custom caching logic) 3. Highly invalid HTTP requests — OkHttp follows RFC strictly 4. Older Android (< 5.0) — use OkHttp 3.12.x branch for API 9+ 5. Older Java (< 8) — use OkHttp 3.12.x branch for Java 7+ **Should not use** OkHttp for: - GET requests with body (use POST instead) - Custom cache implementations (use interceptors) - Invalid HTTP requests (OkHttp follows RFC strictly) - Android < 5.0 (use OkHttp 3.12.x) - Java < 8 (use OkHttp 3.12.x) ## When to Use This Skill Use this skill when the user needs to: - Make HTTP/HTTPS requests in Java or Android - Build REST API clients with connection pooling - Implement response caching - Add request/response interceptors (logging, auth, compression) - Configure TLS versions and cipher suites - Pin certificates for security - Monitor HTTP call performance with EventListener - Test HTTP clients with MockWebServer - Handle redirects, retries, and authentication challenges - Use HTTP/2 multiplexing ## 5.x New Features (vs 4.x) **Key changes in OkHttp 5.x:** - **Kotlin Multiplatform** — Separate JVM and Android artifacts (`okhttp-jvm` for Maven) - **Happy Eyeballs (RFC 6555)** — Fast Fallback enabled by default; concurrent IPv4/IPv6 attempts - **MockWebServer 3** — New coordinate (`mockwebserver3`), no JUnit 4 dependency, immutable API - **GraalVM Native Image** — Automatic support; see `okcurl` module for example - **Java 9 Modules (JPMS)** — Proper `module-info.java` files (5.2+) - **Virtual Threads** — Java 21 virtual threads supported (uses Lock/Condition instead of synchronized) - **Interceptor superpowers (5.4)** — Interceptors can now override OkHttpClient.Builder settings - **Call tags (5.3)** — Attach application-specific metadata to Calls - **Zstd compression (5.2)** — `okhttp-zstd` module for Zstandard compression - **QUERY HTTP method (5.2)** — Support for QUERY method - **HTTP 101 responses (5.2)** — Response.socket for connection upgrades ## Quick Start **Gradle:** ```groovy dependencies { implementation(platform("com.squareup.okhttp3:okhttp-bom:5.4.0")) implementation("com.squareup.okhttp3:okhttp") implementation("com.squareup.okhttp3:logging-interceptor") } ``` **Maven (JVM — must use `okhttp-jvm`):** ```xml <dependencyManagement> <dependencies> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp-bom</artifactId> <version>5.4.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp-jvm</artifactId> </dependency> </dependencies> ``` **Minimal GET:** ```java OkHttpClient client = new OkHttpClient(); Request request = new Request.Builder().url("https://api.example.com/users").build(); try (Response response = client.newCall(request).execute()) { System.out.println(response.body().string()); } ``` **Minimal POST JSON:** ```java RequestBody body = RequestBody.create("{\"name\":\"Alice\"}", MediaType.get("application/json")); Request request = new Request.Builder().url("https://api.example.com/users").post(body).build(); try (Response response = client.newCall(request).execute()) { System.out.println(response.body().string()); } ``` ## Workflow Step 1. **Confirm environment** — Check Java 8+ or Android 5+, choose Maven (`okhttp-jvm`) or Gradle (`okhttp`) Step 2. **Configure OkHttpClient** — Set timeouts, connection pool, cache, interceptors, TLS Step 3. **Build Request** — Set URL, method, headers, body Step 4. **Execute Call** — Synchronous (`execute()`) or asynchronous (`enqueue()`) Step 5. **Handle Response** — Check status, read body, handle errors ## Critical: OkHttpClient Configuration ```java OkHttpClient client = new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .callTimeout(60, TimeUnit.SECONDS) // Entire call timeout .connectionPool(new ConnectionPool(5, 5, TimeUnit.MINUTES)) .cache(new Cache(new File("cache-dir"), 50L * 1024L * 1024L)) // 50 MiB .addInterceptor(new LoggingInterceptor()) // Application interceptor .addNetworkInterceptor(new NetworkInterceptor()) // Network interceptor .followRedirects(true) .followSslRedirects(true) .retryOnConnectionFailure(true) .build(); ``` **Key configuration options:** | Builder Method | Impact | Default | |---------------|--------|---------| | `connectTimeout(int, TimeUnit)` | TCP connection timeout | 10 seconds | | `readTimeout(int, TimeUnit)` | Socket read timeout | 10 seconds | | `writeTimeout(int, TimeUnit)` | Socket write timeout | 10 seconds | | `callTimeout(int, TimeUnit)` | Entire call timeout (all steps) | no limit | | `connectionPool(ConnectionPool)` | Connection pool settings | 5 idle, 5 min keepalive | | `cache(Cache)` | Response cache (off by default) | null | | `followRedirects(boolean)` | Follow HTTP redirects | true | | `followSslRedirects(boolean)` | Follow HTTPS↔HTTP redirects | true | | `retryOnConnectionFailure(boolean)` | Retry on stale connection | true | | `dns(Dns)` | Custom DNS resolver | System DNS | | `proxy(Proxy)` | Single proxy | null (direct) | | `proxySelector(ProxySelector)` | Per-request proxy selection | system default | | `authenticator(Authenticator)` | HTTP auth challenges | none | | `certificatePinner(CertificatePinner)` | Certificate pinning | none | | `sslSocketFactory(SSLSocketFactory, X509TrustManager)` | Custom TLS | platform default | | `connectionSpecs(List<ConnectionSpec>)` | TLS versions and cipher suites | MODERN_TLS | | `eventListenerFactory(EventListener.Factory)` | Event monitoring | none | See [references/configuration.md](references/configuration.md) for full reference. ## Critical: Making Requests **Request building:** ```java Request request = new Request.Builder() .url("https://api.example.com/users/1") .header("Authorization", "Bearer token123") .addHeader("Accept", "application/json") .get() .build(); ``` **POST with JSON body:** ```java RequestBody body = RequestBody.create(jsonString, MediaType.get("application/json")); Request request = new Request.Builder() .url("https://api.example.com/users") .post(body) .build(); ``` **POST with form data:** ```java RequestBody formBody = new FormBody.Builder() .add("username", "alice") .add("password", "secret") .build(); ``` **Multipart upload:** ```java RequestBody fileBody = RequestBody.create(new File("photo.jpg"), MediaType.get("image/jpeg")); RequestBody requestBody = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("title", "My Photo") .addFormDataPart("photo", "photo.jpg", fileBody) .build(); ``` See [references/calls.md](references/calls.md) for PUT/DELETE, request/response lifecycle. ## Critical: Handling Responses **Synchronous:** ```java try (Response response = client.newCall(request).execute()) { if (!response.isSuccessful()) throw new IOException("Unexpected code " + response); String body = response.body().string(); int code = response.code(); String contentType = response.header("Content-Type"); } ``` **Asynchronous:** ```java client.newCall(request).enqueue(new Callback() { @Override public void onFailure(Call call, IOException e) { e.printStackTrace(); } @Override public void onResponse(Call call, Response response) throws IOException { try (ResponseBody body = response.body()) { if (!response.isSuccessful()) throw new IOException("Unexpected code " + response); System.out.println(body.string()); } } }); ``` See [references/calls.md](references/calls.md) for follow-ups, retries, Dispatcher. ## Critical: Interceptors **Application interceptor** — sees the original request, even for cached responses: ```java OkHttpClient client = new OkHttpClient.Builder() .addInterceptor(new LoggingInterceptor()) .build(); ``` **Network interceptor** — sees the actual network request (with OkHttp-added headers): ```java OkHttpClient client = new OkHttpClient.Builder() .addNetworkInterceptor(new LoggingInterceptor()) .build(); ``` **Logging interceptor (built-in):** ```java import okhttp3.logging.HttpLoggingInterceptor; HttpLoggingInterceptor logging = new HttpLoggingInterceptor(); logging.setLevel(HttpLoggingInterceptor.Level.BODY); ``` See [references/interceptors.md](references/interceptors.md) for Application vs Network, GzipRequestInterceptor. ## Critical: Caching **Enable cache:** ```java OkHttpClient client = new OkHttpClient.Builder() .cache(new Cache(new File("cache-dir"), 50L * 1024L * 1024L)) // 50 MiB .build(); ``` **Cache events:** `CacheHit`, `CacheMiss`, `CacheConditionalHit` **Prune cache:** ```java cache.evictAll(); // Clear all Iterator<String> urlIterator = cache.urls(); while (urlIterator.hasNext()) { if (urlIterator.next().startsWith("https://api.example.com/")) urlIterator.remove(); } ```