OkHttp

https://square.github.io/okhttp/
Admin
OkHttp is an efficient HTTP client for Android and Java that supports HTTP/2, connection pooling,...
Tokens:164,609
Snippets:2,225
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### start(inetAddress: InetAddress, port: Int)

Source: https://square.github.io/okhttp/5.x/mockwebserver3/mockwebserver3/-mock-web-server/start.html

Starts the server on the given address and port.

```kotlin
fun start(inetAddress: InetAddress, port: Int)
```

--------------------------------

### start(port: Int = 0)

Source: https://square.github.io/okhttp/5.x/mockwebserver3/mockwebserver3/-mock-web-server/start.html

Starts the server on the loopback interface for the given port.

```kotlin
@JvmOverloads
fun start(port: Int = 0)
```

--------------------------------

### Gradle Local Properties Example

Source: https://square.github.io/okhttp/contribute/contributing

Example of a local.properties file for Gradle setup, including the SDK directory and enabling Gradle caching.

```properties
sdk.dir=PATH_TO_ANDROID_HOME/sdk
org.gradle.caching=true

```

--------------------------------

### start

Source: https://square.github.io/okhttp/5.x/mockwebserver3/mockwebserver3/-mock-web-server/index.html

Starts the server on the loopback interface for the given port.

```kotlin
@JvmOverloads
fun start(port: Int = 0)
```

```kotlin
fun start(inetAddress: InetAddress, port: Int)
```

--------------------------------

### started

Source: https://square.github.io/okhttp/5.x/mockwebserver3/mockwebserver3/-mock-web-server/index.html

Whether the mock web server has started.

```kotlin
val started: Boolean
```

--------------------------------

### MockWebServer.start

Source: https://square.github.io/okhttp/5.x/mockwebserver/okhttp3.mockwebserver/-mock-web-server/index.html

Starts the server on a specified port or address.

```APIDOC
## fun start(port: Int = 0)
## fun start(inetAddress: InetAddress, port: Int)

### Description
Starts the server instance.

### Parameters
- **port** (Int) - Optional - The port to bind to.
- **inetAddress** (InetAddress) - Required - The address to bind to.
```

--------------------------------

### Posting a File

Source: https://square.github.io/okhttp/recipes

This example shows how to use a file as a request body.

```kotlin
  private val client = OkHttpClient()

  fun run() {
    val file = File("README.md")

    val request = Request.Builder()
        .url("https://api.github.com/markdown/raw")
        .post(file.asRequestBody(MEDIA_TYPE_MARKDOWN))
        .build()

    client.newCall(request).execute().use { response ->
      if (!response.isSuccessful) throw IOException("Unexpected code $response")

      println(response.body!!.string())
    }
  }

  companion object {
    val MEDIA_TYPE_MARKDOWN = "text/x-markdown; charset=utf-8".toMediaType()
  }


```

```java
  public static final MediaType MEDIA_TYPE_MARKDOWN
      = MediaType.parse("text/x-markdown; charset=utf-8");

  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    File file = new File("README.md");

    Request request = new Request.Builder()
        .url("https://api.github.com/markdown/raw")
        .post(RequestBody.create(MEDIA_TYPE_MARKDOWN, file))
        .build();

    try (Response response = client.newCall(request).execute()) {
      if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

      System.out.println(response.body().string());
    }
  }


```

--------------------------------

### Headers equality comparison examples

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-headers/equals.html

These examples demonstrate cases where headers are not equal due to differences in order, casing, or values.

```text
Content-Type: text/html
Content-Length: 50
```

```text
Content-Length: 50
Content-Type: text/html
```

```text
content-type: text/html
content-length: 50
```

```text
Content-Type: text/html
Content-Length: 050
```

--------------------------------

### Task Runner Logging Example

Source: https://square.github.io/okhttp/debug_logging

Example log output for task enqueues, starts, and finishes in the OkHttp Task Runner.

```log
[2020-01-01 00:00:00] Q10000 scheduled after   0 µs: OkHttp ConnectionPool
[2020-01-01 00:00:00] Q10000 starting              : OkHttp ConnectionPool
[2020-01-01 00:00:00] Q10000 run again after 300 s : OkHttp ConnectionPool
[2020-01-01 00:00:00] Q10000 finished run in   1 ms: OkHttp ConnectionPool
[2020-01-01 00:00:00] Q10001 scheduled after   0 µs: OkHttp squareup.com applyAndAckSettings
[2020-01-01 00:00:00] Q10001 starting              : OkHttp squareup.com applyAndAckSettings
[2020-01-01 00:00:00] Q10003 scheduled after   0 µs: OkHttp squareup.com onSettings
[2020-01-01 00:00:00] Q10003 starting              : OkHttp squareup.com onSettings
[2020-01-01 00:00:00] Q10001 finished run in   3 ms: OkHttp squareup.com applyAndAckSettings
[2020-01-01 00:00:00] Q10003 finished run in 528 µs: OkHttp squareup.com onSettings
[2020-01-01 00:00:00] Q10000 scheduled after   0 µs: OkHttp ConnectionPool
[2020-01-01 00:00:00] Q10000 starting              : OkHttp ConnectionPool
[2020-01-01 00:00:00] Q10000 run again after 300 s : OkHttp ConnectionPool
[2020-01-01 00:00:00] Q10000 finished run in 739 µs: OkHttp ConnectionPool

```

--------------------------------

### Kotlin Example

Source: https://square.github.io/okhttp/recipes

Demonstrates how to configure and use OkHttp's response caching in Kotlin.

```kotlin
  private val client: OkHttpClient = OkHttpClient.Builder()
      .cache(Cache(
          directory = cacheDirectory,
          maxSize = 10L * 1024L * 1024L // 10 MiB
      ))
      .build()

  fun run() {
    val request = Request.Builder()
        .url("http://publicobject.com/helloworld.txt")
        .build()

    val response1Body = client.newCall(request).execute().use {
      if (!it.isSuccessful) throw IOException("Unexpected code $it")

      println("Response 1 response:          $it")
      println("Response 1 cache response:    ${it.cacheResponse}")
      println("Response 1 network response:  ${it.networkResponse}")
      return@use it.body!!.string()
    }

    val response2Body = client.newCall(request).execute().use {
      if (!it.isSuccessful) throw IOException("Unexpected code $it")

      println("Response 2 response:          $it")
      println("Response 2 cache response:    ${it.cacheResponse}")
      println("Response 2 network response:  ${it.networkResponse}")
      return@use it.body!!.string()
    }

    println("Response 2 equals Response 1? " + (response1Body == response2Body))


```

--------------------------------

### Java Example

Source: https://square.github.io/okhttp/recipes

Demonstrates how to configure and use OkHttp's response caching in Java.

```java
  private final OkHttpClient client;

  public CacheResponse(File cacheDirectory) throws Exception {
    int cacheSize = 10 * 1024 * 1024; // 10 MiB
    Cache cache = new Cache(cacheDirectory, cacheSize);

    client = new OkHttpClient.Builder()
        .cache(cache)
        .build();
  }

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://publicobject.com/helloworld.txt")
        .build();

    String response1Body;
    try (Response response1 = client.newCall(request).execute()) {
      if (!response1.isSuccessful()) throw new IOException("Unexpected code " + response1);

      response1Body = response1.body().string();
      System.out.println("Response 1 response:          " + response1);
      System.out.println("Response 1 cache response:    " + response1.cacheResponse());
      System.out.println("Response 1 network response:  " + response1.networkResponse());
    }

    String response2Body;
    try (Response response2 = client.newCall(request).execute()) {
      if (!response2.isSuccessful()) throw new IOException("Unexpected code " + response2);

      response2Body = response2.body().string();
      System.out.println("Response 2 response:          " + response2);
      System.out.println("Response 2 cache response:    " + response2.cacheResponse());
      System.out.println("Response 2 network response:  " + response2.networkResponse());
    }

    System.out.println("Response 2 equals Response 1? " + response1Body.equals(response2Body));
  }


```

--------------------------------

### Configure Certificate Pinning with a Broken Configuration

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-certificate-pinner

Initial setup using a dummy hash to trigger a failure, which reveals the correct certificate hashes in the exception message.

```java
String hostname = "publicobject.com";
CertificatePinner certificatePinner = new CertificatePinner.Builder()
    .add(hostname, "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
    .build();
OkHttpClient client = OkHttpClient.Builder()
    .certificatePinner(certificatePinner)
    .build();

Request request = new Request.Builder()
    .url("https://" + hostname)
    .build();
client.newCall(request).execute();
```

--------------------------------

### HTTP/2 Frame Logging Example

Source: https://square.github.io/okhttp/debug_logging

Example log output for inbound (<<) and outbound (>>) frames for HTTP/2 connections.

```log
[2020-01-01 00:00:00] >> CONNECTION 505249202a20485454502f322e300d0a0d0a534d0d0a0d0a
[2020-01-01 00:00:00] >> 0x00000000     6 SETTINGS
[2020-01-01 00:00:00] >> 0x00000000     4 WINDOW_UPDATE
[2020-01-01 00:00:00] >> 0x00000003    47 HEADERS       END_STREAM|END_HEADERS
[2020-01-01 00:00:00] << 0x00000000     6 SETTINGS
[2020-01-01 00:00:00] << 0x00000000     0 SETTINGS      ACK
[2020-01-01 00:00:00] << 0x00000000     4 WINDOW_UPDATE
[2020-01-01 00:00:00] >> 0x00000000     0 SETTINGS      ACK
[2020-01-01 00:00:00] << 0x00000003   322 HEADERS       END_HEADERS
[2020-01-01 00:00:00] << 0x00000003   288 DATA
[2020-01-01 00:00:00] << 0x00000003     0 DATA          END_STREAM
[2020-01-01 00:00:00] << 0x00000000     8 GOAWAY
[2020-01-01 00:00:05] << 0x00000000     8 GOAWAY

```

--------------------------------

### Posting a String

Source: https://square.github.io/okhttp/recipes

Example of how to send a string as a request body using HTTP POST.

```kotlin
  private val client = OkHttpClient()

  fun run() {
    val postBody = """        |Releases
        |--------
        |
        | * _1.0_ May 6, 2013
        | * _1.1_ June 15, 2013
        | * _1.2_ August 11, 2013
        |""".trimMargin()

    val request = Request.Builder()
        .url("https://api.github.com/markdown/raw")
        .post(postBody.toRequestBody(MEDIA_TYPE_MARKDOWN))
        .build()

    client.newCall(request).execute().use { response ->
      if (!response.isSuccessful) throw IOException("Unexpected code $response")

      println(response.body!!.string())
    }
  }

  companion object {
    val MEDIA_TYPE_MARKDOWN = "text/x-markdown; charset=utf-8".toMediaType()
  }


```

```java
  public static final MediaType MEDIA_TYPE_MARKDOWN
      = MediaType.parse("text/x-markdown; charset=utf-8");

  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    String postBody = "" +
        "Releases\n" +
        "--------\n" +
        "\n" +
        " * _1.0_ May 6, 2013\n" +
        " * _1.1_ June 15, 2013\n" +
        " * _1.2_ August 11, 2013\n";

    Request request = new Request.Builder()
        .url("https://api.github.com/markdown/raw")
        .post(RequestBody.create(MEDIA_TYPE_MARKDOWN, postBody))
        .build();

    try (Response response = client.newCall(request).execute()) {
      if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

      System.out.println(response.body().string());
    }
  }


```

--------------------------------

### Java Example

Source: https://square.github.io/okhttp/recipes

This Java code snippet demonstrates how to achieve the same JSON parsing with OkHttp and Moshi using Java.

```Java
private final OkHttpClient client = new OkHttpClient();
private final Moshi moshi = new Moshi.Builder().build();
private final JsonAdapter<Gist> gistJsonAdapter = moshi.adapter(Gist.class);

public void run() throws Exception {
  Request request = new Request.Builder()
      .url("https://api.github.com/gists/c2a7c39532239ff261be")
      .build();
  try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    Gist gist = gistJsonAdapter.fromJson(response.body().source());

    for (Map.Entry<String, GistFile> entry : gist.files.entrySet()) {
      System.out.println(entry.getKey());
      System.out.println(entry.getValue().content);
    }
  }
}

static class Gist {
  Map<String, GistFile> files;
}

static class GistFile {
  String content;
}
```

--------------------------------

### Post Streaming

Source: https://square.github.io/okhttp/recipes

This example demonstrates how to POST a request body as a stream, generating content as it's written and streaming directly into an Okio buffered sink.

```kotlin
  private val client = OkHttpClient()

  fun run() {
    val requestBody = object : RequestBody() {
      override fun contentType() = MEDIA_TYPE_MARKDOWN

      override fun writeTo(sink: BufferedSink) {
        sink.writeUtf8("Numbers\n")
        sink.writeUtf8("-------\n")
        for (i in 2..997) {
          sink.writeUtf8(String.format(" * $i = ${factor(i)}\n"))
        }
      }

      private fun factor(n: Int): String {
        for (i in 2 until n) {
          val x = n / i
          if (x * i == n) return "${factor(x)} × $i"
        }
        return n.toString()
      }
    }

    val request = Request.Builder()
        .url("https://api.github.com/markdown/raw")
        .post(requestBody)
        .build()

    client.newCall(request).execute().use { response ->
      if (!response.isSuccessful) throw IOException("Unexpected code $response")

      println(response.body!!.string())
    }
  }

  companion object {
    val MEDIA_TYPE_MARKDOWN = "text/x-markdown; charset=utf-8".toMediaType()
  }


```

```java
  public static final MediaType MEDIA_TYPE_MARKDOWN
      = MediaType.parse("text/x-markdown; charset=utf-8");

  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    RequestBody requestBody = new RequestBody() {
      @Override public MediaType contentType() {
        return MEDIA_TYPE_MARKDOWN;
      }

      @Override public void writeTo(BufferedSink sink) throws IOException {
        sink.writeUtf8("Numbers\n");
        sink.writeUtf8("-------\n");
        for (int i = 2; i <= 997; i++) {
          sink.writeUtf8(String.format(" * %s = %s\n", i, factor(i)));
        }
      }

      private String factor(int n) {
        for (int i = 2; i < n; i++) {
          int x = n / i;
          if (x * i == n) return factor(x) + " × " + i;
        }
        return Integer.toString(n);
      }
    };

    Request request = new Request.Builder()
        .url("https://api.github.com/markdown/raw")
        .post(requestBody)
        .build();

    try (Response response = client.newCall(request).execute()) {
      if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

      System.out.println(response.body().string());
    }
  }


```

--------------------------------

### connectStart(Call, InetSocketAddress, Proxy)

Source: https://square.github.io/okhttp/5.x/logging-interceptor/okhttp3.logging/-logging-event-listener/connect-start.html

Invoked when a connection attempt is started. This method is part of the EventListener interface used for logging connection events.

```APIDOC
## connectStart

### Signature
`open override fun connectStart(call: Call, inetSocketAddress: InetSocketAddress, proxy: Proxy)`

### Description
This method is called when the client starts a connection to the server. It provides the call instance, the target socket address, and the proxy being used for the connection.

### Parameters
- **call** (Call) - The call that initiated the connection.
- **inetSocketAddress** (InetSocketAddress) - The address of the server being connected to.
- **proxy** (Proxy) - The proxy server being used for this connection.
```

--------------------------------

### Upload Progress Example

Source: https://square.github.io/okhttp/recipes

This Java code demonstrates how to create a RequestBody that tracks upload progress using a ProgressListener.

```java
public static void main(String... args) throws Exception {
  new UploadProgress().run();
}

private static class ProgressRequestBody extends RequestBody {
  private final ProgressListener progressListener;
  private final RequestBody delegate;

  public ProgressRequestBody(RequestBody delegate, ProgressListener progressListener) {
    this.delegate = delegate;
    this.progressListener = progressListener;
  }

  @Override public MediaType contentType() {
    return delegate.contentType();
  }

  @Override public long contentLength() throws IOException {
    return delegate.contentLength();
  }

  @Override public void writeTo(BufferedSink sink) throws IOException {
    BufferedSink bufferedSink = Okio.buffer(sink(sink));
    delegate.writeTo(bufferedSink);
    bufferedSink.flush();
  }

  public Sink sink(Sink sink) {
    return new ForwardingSink(sink) {
      private long totalBytesWritten = 0L;
      private boolean completed = false;

      @Override public void write(Buffer source, long byteCount) throws IOException {
        super.write(source, byteCount);
        totalBytesWritten += byteCount;
        progressListener.update(totalBytesWritten, contentLength(), completed);
      }

      @Override public void close() throws IOException {
        super.close();
        if (!completed) {
          completed = true;
          progressListener.update(totalBytesWritten, contentLength(), completed);
        }
      }
    };
  }
}

interface ProgressListener {
  void update(long bytesWritten, long contentLength, boolean done);
}
```

--------------------------------

### Download a URL with OkHttp

Source: https://square.github.io/okhttp

Performs a synchronous GET request and returns the response body as a string.

```java
OkHttpClient client = new OkHttpClient();

String run(String url) throws IOException {
  Request request = new Request.Builder()
      .url(url)
      .build();

  try (Response response = client.newCall(request).execute()) {
    return response.body().string();
  }
}
```

--------------------------------

### Synchronous Get

Source: https://square.github.io/okhttp/recipes

Download a file, print its headers, and print its response body as a string.

```Kotlin
  private val client = OkHttpClient()

  fun run() {
    val request = Request.Builder()
        .url("https://publicobject.com/helloworld.txt")
        .build()

    client.newCall(request).execute().use { response ->
      if (!response.isSuccessful) throw IOException("Unexpected code $response")

      for ((name, value) in response.headers) {
        println("$name: $value")
      }

      println(response.body!!.string())
    }
  }


```

```Java
  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("https://publicobject.com/helloworld.txt")
        .build();

    try (Response response = client.newCall(request).execute()) {
      if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

      Headers responseHeaders = response.headers();
      for (int i = 0; i < responseHeaders.size(); i++) {
        System.out.println(responseHeaders.name(i) + ": " + responseHeaders.value(i));
      }

      System.out.println(response.body().string());
    }
  }


```

--------------------------------

### Java Module Visibility Error

Source: https://square.github.io/okhttp

Example of a build failure occurring when attempting to access internal OkHttp packages from a module.

```text
error: package okhttp3.internal.platform is not visible
    okhttp3.internal.platform.Platform.get();
                    ^
  (package okhttp3.internal.platform is declared in module okhttp3,
    which does not export it to module com.bigco.sdk)
```

--------------------------------

### Kotlin Example

Source: https://square.github.io/okhttp/recipes

This Kotlin code snippet shows how to use OkHttp to fetch JSON data from a GitHub API and parse it into Kotlin data classes using Moshi.

```Kotlin
private val client = OkHttpClient()
private val moshi = Moshi.Builder().build()
private val gistJsonAdapter = moshi.adapter(Gist::class.java)

fun run() {
  val request = Request.Builder()
      .url("https://api.github.com/gists/c2a7c39532239ff261be")
      .build()
  client.newCall(request).execute().use { response ->
    if (!response.isSuccessful) throw IOException("Unexpected code $response")

    val gist = gistJsonAdapter.fromJson(response.body!!.source())

    for ((key, value) in gist!!.files!!) {
      println(key)
      println(value.content)
    }
  }
}

@JsonClass(generateAdapter = true)
data class Gist(var files: Map<String, GistFile>?)

@JsonClass(generateAdapter = true)
data class GistFile(var content: String?)
```

--------------------------------

### OkHttpClient Initialization

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/index.html

Methods for creating and configuring an OkHttpClient instance.

```APIDOC
## OkHttpClient()

### Description
Creates a new OkHttpClient instance with default settings. It is recommended to share this instance across the application.

## OkHttpClient.Builder()

### Description
Creates a builder to configure a custom OkHttpClient instance with specific settings like interceptors or cache.

## newBuilder()

### Description
Creates a new builder derived from an existing OkHttpClient instance, sharing the same connection pool and thread pools while allowing configuration overrides.
```

--------------------------------

### Asynchronous Get

Source: https://square.github.io/okhttp/recipes

Download a file on a worker thread, and get called back when the response is readable.

```Kotlin
  private val client = OkHttpClient()

  fun run() {
    val request = Request.Builder()
        .url("http://publicobject.com/helloworld.txt")
        .build()

    client.newCall(request).enqueue(object : Callback {
      override fun onFailure(call: Call, e: IOException) {
        e.printStackTrace()
      }

      override fun onResponse(call: Call, response: Response) {
        response.use {
          if (!response.isSuccessful) throw IOException("Unexpected code $response")

          for ((name, value) in response.headers) {
            println("$name: $value")
          }

          println(response.body!!.string())
        }
      }
    })
  }


```

```Java
  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://publicobject.com/helloworld.txt")
        .build();

    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 responseBody = response.body()) {
          if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

          Headers responseHeaders = response.headers();
          for (int i = 0, size = responseHeaders.size(); i < size; i++) {
            System.out.println(responseHeaders.name(i) + ": " + responseHeaders.value(i));
          }

          System.out.println(responseBody.string());
        }
      }
    });
  }


```

--------------------------------

### initialize

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http/index.html

Configures the ApplicationContext for Android. This is typically handled automatically but may be required if AndroidX Startup Initializer is disabled or during specific testing scenarios.

```APIDOC
### Method
initialize(applicationContext: Context)

### Description
Configures the ApplicationContext for the OkHttp library.

### Parameters
- **applicationContext** (Context) - Required - The Android application context to initialize.
```

--------------------------------

### SocketPolicy Functions

Source: https://square.github.io/okhttp/5.x/mockwebserver/okhttp3.mockwebserver/-socket-policy/index.html

This lists the functions available for the SocketPolicy enum, specifically 'valueOf' to get an enum constant by name and 'values' to get an array of all constants.

```kotlin
fun valueOf(value: String): SocketPolicy
fun values(): Array<SocketPolicy>
```

--------------------------------

### Configure Custom SSLSocketFactory

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/-builder/ssl-socket-factory.html

Demonstrates how to manually initialize an SSLContext and TrustManagerFactory to configure an OkHttpClient with custom SSL settings.

```java
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(
TrustManagerFactory.getDefaultAlgorithm());
trustManagerFactory.init((KeyStore) null);
TrustManager[] trustManagers = trustManagerFactory.getTrustManagers();
if (trustManagers.length != 1 || !(trustManagers[0] instanceof X509TrustManager)) {
    throw new IllegalStateException("Unexpected default trust managers:"
        + Arrays.toString(trustManagers));
}
X509TrustManager trustManager = (X509TrustManager) trustManagers[0];

SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(null, new TrustManager[] { trustManager }, null);
SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory();

OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(sslSocketFactory, trustManager)
    .build();
```

--------------------------------

### Create a Default OkHttpClient Instance

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/index.html

Instantiate a shared OkHttpClient using default settings.

```java
// The singleton HTTP client.
public final OkHttpClient client = new OkHttpClient();
```

--------------------------------

### build()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/-builder/index.html

Finalizes the configuration and returns a new OkHttpClient instance.

```APIDOC
### Method
`build(): OkHttpClient`

Creates and returns a new `OkHttpClient` instance based on the current configuration of this builder.
```

--------------------------------

### Application Interceptor Example

Source: https://square.github.io/okhttp/features/interceptors

Registering an application interceptor by calling addInterceptor() on OkHttpClient.Builder.

```Java
OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new LoggingInterceptor())
    .build();

Request request = new Request.Builder()
    .url("http://www.publicobject.com/helloworld.txt")
    .header("User-Agent", "OkHttp Example")
    .build();

Response response = client.newCall(request).execute();
response.body().close();
```

--------------------------------

### dnsStart(call: Call, domainName: String)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-event-listener/dns-start.html

Invoked just prior to a DNS lookup. This method may be called multiple times for a single call, such as during redirects, but will not be invoked if an existing pooled connection is reused.

```APIDOC
## dnsStart(call: Call, domainName: String)

### Description
Invoked just prior to a DNS lookup. This method can be triggered multiple times for a single call, for instance, if the request results in a redirect to a different host. It is not invoked if the call reuses an existing pooled connection.

### Parameters
- **call** (Call) - The call that is initiating the DNS lookup.
- **domainName** (String) - The hostname being resolved.
```

--------------------------------

### Replace MediaType.get() with toMediaType()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-media-type/-companion/get.html

Use the toMediaType extension function as a replacement for the deprecated get method.

```kotlin
import okhttp3.MediaType.Companion.toMediaType
```

```kotlin
mediaType.toMediaType()
```

--------------------------------

### val method: String

Source: https://square.github.io/okhttp/5.x/mockwebserver/okhttp3.mockwebserver/-push-promise/method.html

Retrieves the HTTP method (e.g., GET, POST) of the push promise.

```APIDOC
## val method: String

### Description
Returns the HTTP method associated with this push promise.

### Signature
`val method: String`

### Usage
Access this property directly on a `PushPromise` instance to obtain the method string.
```

--------------------------------

### build

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-multipart-body/-builder/index.html

Assembles the configured parts into a MultipartBody instance.

```APIDOC
## build()

### Description
Assemble the specified parts into a request body.

### Returns
- **MultipartBody** - The constructed request body.
```

--------------------------------

### Network Interceptor Example

Source: https://square.github.io/okhttp/features/interceptors

Registering a network interceptor by calling addNetworkInterceptor() instead of addInterceptor().

```Java
OkHttpClient client = new OkHttpClient.Builder()
    .addNetworkInterceptor(new LoggingInterceptor())
    .build();

Request request = new Request.Builder()
    .url("http://www.publicobject.com/helloworld.txt")
    .header("User-Agent", "OkHttp Example")
    .build();

Response response = client.newCall(request).execute();
response.body().close();
```

--------------------------------

### fun initialize()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache/initialize.html

Initializes the cache by reading journal files and building in-memory cache information. If not called explicitly, OkHttp performs lazy initialization upon the first cache access.

```APIDOC
## fun initialize()

### Description
Initializes the cache. This process involves reading the journal files from storage and building the necessary in-memory cache information. 

### Usage
It is recommended to call this method during the application's initialization phase, preferably within a background worker thread, as the time required depends on the journal file size and the total cache size. If this method is not called, OkHttp will perform lazy initialization upon the first usage of the cache.
```

--------------------------------

### BASIC Log Example

Source: https://square.github.io/okhttp/5.x/logging-interceptor/okhttp3.logging/-http-logging-interceptor/-level/-b-a-s-i-c/index.html

Logs request and response lines.

```text
--> POST /greeting http/1.1 (3-byte body)

<-- 200 OK (22ms, 6-byte body)
```

--------------------------------

### proxySelectStart(call: Call, url: HttpUrl)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-event-listener/proxy-select-start.html

Invoked prior to a proxy selection. This will be invoked for route selection regardless of whether the client is configured with a single proxy, a proxy selector, or neither.

```APIDOC
## proxySelectStart(call: Call, url: HttpUrl)

### Description
Invoked prior to a proxy selection. This will be invoked for route selection regardless of whether the client is configured with a single proxy, a proxy selector, or neither.

### Parameters
- **call** (Call) - The call that is initiating the proxy selection.
- **url** (HttpUrl) - A URL with only the scheme, hostname, and port specified.
```

--------------------------------

### Configure HTTP/2 Prior Knowledge with Proxy

Source: https://square.github.io/okhttp/changelog

Demonstrates the curl command arguments required to use HTTP/2 prior knowledge through an HTTP proxy.

```bash
curl \
  --http2-prior-knowledge \
  --proxy localhost:8888 \
  --proxytunnel \
  http://squareup.com/robots.txt
```

--------------------------------

### Configure OkHttp Cache

Source: https://square.github.io/okhttp/features/caching

Initialize an OkHttpClient with a cache directory and a maximum size limit.

```kotlin
  private val client: OkHttpClient = OkHttpClient.Builder()
      .cache(Cache(
          directory = File(application.cacheDir, "http_cache"),
          // $0.05 worth of phone storage in 2020
          maxSize = 50L * 1024L * 1024L // 50 MiB
      ))
      .build()
```

--------------------------------

### Build and Run GraalVM Native Image

Source: https://square.github.io/okhttp

Commands to build a native image using Gradle and execute the resulting binary.

```bash
$ ./gradlew okcurl:nativeImage
$ ./okcurl/build/graal/okcurl https://httpbin.org/get
```

--------------------------------

### Create a Custom OkHttpClient Instance

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/index.html

Configure a shared OkHttpClient instance with custom settings like interceptors and cache.

```java
// The singleton HTTP client.
public final OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new HttpLoggingInterceptor())
    .cache(new Cache(cacheDir, cacheSize))
    .build();
```

--------------------------------

### HEADERS Example

Source: https://square.github.io/okhttp/5.x/logging-interceptor/okhttp3.logging/-http-logging-interceptor/-level/-h-e-a-d-e-r-s/index.html

Logs request and response lines and their respective headers.

```http
--> POST /greeting http/1.1
Host: example.com
Content-Type: plain/text
Content-Length: 3
--> END POST

<-- 200 OK (22ms)
Content-Type: plain/text
Content-Length: 6
<-- END HTTP
```

--------------------------------

### Replace Deprecated SSLSession Handshake

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-handshake/-companion/get.html

Use the handshake() extension function instead of the deprecated get(SSLSession) method.

```kotlin
sslSession.handshake()
```

--------------------------------

### Initialize OkHttp with ApplicationContext

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http/initialize.html

This function configures the ApplicationContext for OkHttp. It's primarily needed when the AndroidX Startup Initializer is disabled or when running Robolectric tests. The absence of a valid Context can affect cookie and URL domain handling.

```kotlin
fun initialize(applicationContext: Context)
```

--------------------------------

### get()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-trailers-source/index.html

Returns the trailers that follow an HTTP response, blocking if they are not yet available. Implementations should respond to Call.cancel by throwing an IOException.

```APIDOC
## abstract fun get(): Headers

### Description
Returns the trailers that follow an HTTP response, blocking if they aren't ready yet. Implementations of this interface should respond to Call.cancel by immediately throwing an IOException.

### Returns
- **Headers** - The trailers associated with the response.
```

--------------------------------

### add(name: String, value: Instant)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-headers/-builder/add.html

Adds a header with the specified name and a formatted instant value.

```APIDOC
### fun add(name: String, value: Instant)

Add a header with the specified name and formatted instant. Does validation of header names and value.
```

--------------------------------

### Making Concurrent HTTP Requests

Source: https://square.github.io/okhttp/features/events

Example of using the PrintingEventListener to race a pair of concurrent HTTP requests.

```java
Request washingtonPostRequest = new Request.Builder()
    .url("https://www.washingtonpost.com/")
    .build();
client.newCall(washingtonPostRequest).enqueue(new Callback() {
  ...
});

Request newYorkTimesRequest = new Request.Builder()
    .url("https://www.nytimes.com/")
    .build();
client.newCall(newYorkTimesRequest).enqueue(new Callback() {
  ...
});

```

--------------------------------

### OkHttpClient()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/index.html

Creates a new OkHttpClient instance.

```APIDOC
### OkHttpClient()

Creates a new instance of OkHttpClient.
```

--------------------------------

### fun responseBodyStart(call: Call)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-event-listener/response-body-start.html

Invoked when data from the response body is first available to the application. This method is typically called immediately before bytes are returned to the application, or when the response body is closed.

```APIDOC
## responseBodyStart

### Description
Invoked when data from the response body is first available to the application. This is typically invoked immediately before bytes are returned to the application. If the response body is empty, this is invoked immediately before returning that to the application.

### Signature
`open fun responseBodyStart(call: Call)`

### Parameters
- **call** (Call) - The call that is receiving the response body.

### Notes
- If the application closes the response body before attempting a read, this is invoked at the time it is closed.
- The connection is implicit and generally relates to the last connectionAcquired event.
- This is usually invoked only once per call, with exceptions for cases like failure recovery.
```

--------------------------------

### initialize()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache/index.html

Initializes the cache by reading journal files and building in-memory information.

```APIDOC
### initialize()

Initialize the cache. This will include reading the journal files from the storage and building up the necessary in-memory cache information.
```

--------------------------------

### Example of BODY logging

Source: https://square.github.io/okhttp/5.x/logging-interceptor/okhttp3.logging/-http-logging-interceptor/-level/-b-o-d-y/index.html

Logs request and response lines and their respective headers and bodies (if present).

```http
--> POST /greeting http/1.1
Host: example.com
Content-Type: plain/text
Content-Length: 3

Hi?
--> END POST

<-- 200 OK (22ms)
Content-Type: plain/text
Content-Length: 6

Hello!
<-- END HTTP
```

--------------------------------

### build()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-certificate-pinner/-builder/index.html

Constructs the CertificatePinner instance from the configured pins.

```APIDOC
## fun build(): CertificatePinner

### Description
Creates and returns a new CertificatePinner instance based on the pins added to this builder.

### Returns
- **CertificatePinner** - The configured certificate pinner instance.
```

--------------------------------

### Certificate Pinning Failure Exception

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-certificate-pinner

Example of the SSLPeerUnverifiedException thrown when certificate pinning fails, providing the actual peer certificate chain hashes.

```text
javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!
Peer certificate chain:
    sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=: CN=publicobject.com, OU=PositiveSSL
    sha256/klO23nT2ehFDXCfx3eHTDRESMz3asj1muO+4aIdjiuY=: CN=COMODO RSA Secure Server CA
    sha256/grX4Ta9HpZx6tSHkmCrvpApTQGo67CYDnvprLg5yRME=: CN=COMODO RSA Certification Authority
    sha256/lCppFqbkrlJ3EcVFAkeip0+44VaoJUymbnOaEUk7tEU=: CN=AddTrust External CA Root
Pinned certificates for publicobject.com:
    sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
  at okhttp3.CertificatePinner.check(CertificatePinner.java)
  at okhttp3.Connection.upgradeToTls(Connection.java)
  at okhttp3.Connection.connect(Connection.java)
  at okhttp3.Connection.connectAndSetOwner(Connection.java)
```

--------------------------------

### build()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-form-body/-builder/index.html

Constructs the FormBody instance.

```APIDOC
## Method: build()

### Description
Finalizes the construction of the FormBody and returns the resulting object.

### Response
- **FormBody** - The constructed FormBody instance.
```

--------------------------------

### Add MockWebServer Dependency

Source: https://square.github.io/okhttp

Include the MockWebServer library in your project for testing HTTP, HTTPS, and HTTP/2 clients.

```kotlin
testImplementation("com.squareup.okhttp3:mockwebserver3:5.4.0")
```

--------------------------------

### operator fun get(name: String): String?

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-headers/get.html

Retrieves the last value corresponding to the specified field name from the headers, or null if the field is not present.

```APIDOC
## operator fun get(name: String): String?

### Description
Returns the last value corresponding to the specified field name. If no value is found for the given name, it returns null.

### Parameters
- **name** (String) - Required - The name of the header field to retrieve.

### Returns
- **String?** - The last value associated with the header name, or null if not found.
```

--------------------------------

### val encodedPath: String

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-http-url/encoded-path.html

Retrieves the entire path of the URL, encoded for use in HTTP resource resolution. The returned string will always start with a forward slash.

```APIDOC
## val encodedPath: String

### Description
Returns the entire path of this URL encoded for use in HTTP resource resolution. The returned path will always start with "/".

### Usage
```kotlin
val url = "http://host/a/b%20c/d".toHttpUrl()
val path = url.encodedPath // Returns "/a/b%20c/d"
```

### Examples
| URL | encodedPath |
| --- | --- |
| http://host/ | "/" |
| http://host/a/b/c | "/a/b/c" |
| http://host/a/b%20c/d | "/a/b%20c/d" |
```

--------------------------------

### operator fun get(name: String): String?

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-headers/-builder/get.html

Retrieves the value of the header with the specified name. This is equivalent to calling build().get(name) but is optimized for performance.

```APIDOC
## operator fun get(name: String): String?

### Description
Retrieves the value associated with the specified header name. This method is equivalent to calling `build().get(name)` but is potentially faster.

### Parameters
- **name** (String) - The name of the header to retrieve.

### Returns
- **String?** - The value of the header if found, otherwise null.
```

--------------------------------

### Running Android Tests

Source: https://square.github.io/okhttp/contribute/contributing

Command to run Android tests using Gradle, specifying the Android SDK root and enabling Android build.

```bash
$ ANDROID_SDK_ROOT=PATH_TO_ANDROID_HOME/sdk ./gradlew :android-test:connectedCheck -PandroidBuild=true

```

--------------------------------

### var maxRequests: Int

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-dispatcher/max-requests.html

Gets or sets the maximum number of requests to execute concurrently. Requests exceeding this limit are queued in memory until running calls complete.

```APIDOC
## Dispatcher.maxRequests

### Description
The maximum number of requests to execute concurrently. Above this limit, requests queue in memory, waiting for the running calls to complete. If more than maxRequests requests are in flight when this is invoked, those requests will remain in flight.

### Signature
`var maxRequests: Int`
```

--------------------------------

### build()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-connection-spec/-builder/index.html

Finalizes the configuration and returns a new ConnectionSpec instance.

```APIDOC
### Method
`build(): ConnectionSpec`

Returns a `ConnectionSpec` configured with the settings defined in this builder.
```

--------------------------------

### build()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache-control/-builder/index.html

Finalizes the configuration and returns a CacheControl instance.

```APIDOC
## build()

### Description
Returns a CacheControl object configured with the settings applied to this builder.
```

--------------------------------

### Address(String, Int, Dns, SocketFactory, SSLSocketFactory?, HostnameVerifier?, CertificatePinner?, Authenticator, Proxy?, List<Protocol>, List<ConnectionSpec>, ProxySelector)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-address/-address.html

Constructs a new Address instance with the specified network and security parameters.

```APIDOC
## Address Constructor

### Description
Creates a new Address instance used to define the parameters for a network connection.

### Signature
`Address(uriHost: String, uriPort: Int, dns: Dns, socketFactory: SocketFactory, sslSocketFactory: SSLSocketFactory?, hostnameVerifier: HostnameVerifier?, certificatePinner: CertificatePinner?, proxyAuthenticator: Authenticator, proxy: Proxy?, protocols: List<Protocol>, connectionSpecs: List<ConnectionSpec>, proxySelector: ProxySelector)`

### Parameters
- **uriHost** (String) - The host name or IP address.
- **uriPort** (Int) - The port number.
- **dns** (Dns) - The DNS service to resolve host names.
- **socketFactory** (SocketFactory) - The factory for creating sockets.
- **sslSocketFactory** (SSLSocketFactory?) - The factory for SSL sockets, or null for non-secure connections.
- **hostnameVerifier** (HostnameVerifier?) - The verifier for hostnames, or null.
- **certificatePinner** (CertificatePinner?) - The certificate pinner, or null.
- **proxyAuthenticator** (Authenticator) - The authenticator for proxy connections.
- **proxy** (Proxy?) - The proxy to use, or null.
- **protocols** (List<Protocol>) - The list of supported protocols.
- **connectionSpecs** (List<ConnectionSpec>) - The list of supported connection specifications.
- **proxySelector** (ProxySelector) - The proxy selector.
```

--------------------------------

### addEncodedPathSegments(String encodedPathSegments)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-http-url/-builder/add-encoded-path-segments.html

Adds a set of encoded path segments separated by a slash (either \ or /). If the input string starts with a slash, the resulting URL will have an empty path segment.

```APIDOC
## addEncodedPathSegments(String encodedPathSegments)

### Description
Adds a set of encoded path segments separated by a slash (either `\\` or `/`) to the URL builder. If the provided string starts with a slash, the resulting URL will contain an empty path segment.

### Signature
`fun addEncodedPathSegments(encodedPathSegments: String): HttpUrl.Builder`

### Parameters
- **encodedPathSegments** (String) - The encoded path segments to add, separated by slashes.

### Returns
- **HttpUrl.Builder** - The current builder instance for method chaining.
```

--------------------------------

### connectionAcquired(call: Call, connection: Connection)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-event-listener/connection-acquired.html

Invoked after a connection has been acquired for the call. This can be invoked more than 1 time for a single Call, for example, if the response to the Call.request is a redirect to a different address.

```APIDOC
## connectionAcquired

### Signature
`open fun connectionAcquired(call: Call, connection: Connection)`

### Description
Invoked after a connection has been acquired for the `call`. This can be invoked more than 1 time for a single Call, for example, if the response to the Call.request is a redirect to a different address.

### Parameters
- **call** (Call) - The call that acquired the connection.
- **connection** (Connection) - The connection that was acquired.
```

--------------------------------

### Builder()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/-builder/index.html

Creates a new instance of the OkHttpClient.Builder.

```APIDOC
### Constructor
`Builder()`

Creates a new builder instance for configuring an `OkHttpClient`.
```

--------------------------------

### ConnectionPool()

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-connection-pool/-connection-pool.html

Creates a new connection pool with default settings.

```APIDOC
### Constructor
ConnectionPool()

### Description
Creates a new connection pool using default values for idle connections and keep-alive duration.
```

--------------------------------

### val callTimeoutMillis: Int

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/call-timeout-millis.html

Retrieves the default call timeout in milliseconds. This timeout applies to the entire call duration, with specific behavior for WebSockets and duplex calls where it applies only to the initial setup.

```APIDOC
## val callTimeoutMillis: Int

### Description
Returns the default call timeout in milliseconds. By default, there is no timeout for complete calls, though connect, write, and read actions within a call have their own timeouts. For WebSockets and duplex calls, this timeout applies only to the initial setup.

### Type
Int
```

--------------------------------

### fun toString(): String

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-protocol/to-string.html

Returns the string used to identify this protocol for ALPN, like 'http/1.1', 'spdy/3.1' or 'h2'.

```APIDOC
## fun toString(): String

### Description
Returns the string used to identify this protocol for ALPN (Application-Layer Protocol Negotiation), such as "http/1.1", "spdy/3.1", or "h2".

### Returns
- **String** - The protocol identifier string.
```

--------------------------------

### addPathSegments(String pathSegments)

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-http-url/-builder/add-path-segments.html

Adds a set of path segments separated by a slash (either \ or /) to the URL builder. If the input string starts with a slash, the resulting URL will contain an empty path segment.

```APIDOC
## addPathSegments(String pathSegments)

### Description
Adds a set of path segments separated by a slash (either \ or /) to the URL builder. If `pathSegments` starts with a slash, the resulting URL will have an empty path segment.

### Signature
`fun addPathSegments(pathSegments: String): HttpUrl.Builder`

### Parameters
- **pathSegments** (String) - Required - A string containing path segments separated by slashes.

### Returns
- **HttpUrl.Builder** - The current builder instance for method chaining.
```

--------------------------------

### Generate cURL command from Request

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-request/to-curl.html

This example shows the output format of the toCurl method. Note that calling this method consumes the request body, which may cause issues if the body is a one-time stream.

```bash
curl 'https://example.com/api' \
  -X PUT \
  -H 'Authorization: Bearer token' \
  --data '{"key":"value"}'
```

--------------------------------

### fun withCharset(charset: Charset): Challenge

Source: https://square.github.io/okhttp/5.x/okhttp/okhttp3/-challenge/with-charset.html

Returns a copy of this challenge that expects a credential encoded with the specified charset.

```APIDOC
## fun withCharset(charset: Charset): Challenge

### Description
Returns a copy of this challenge that expects a credential encoded with the specified charset.

### Parameters
- **charset** (Charset) - Required - The character set to be used for encoding the credential.
```
Tokens:
Raw