API client / Getting started / Customize

Customize your Kotlin client

You can customize the behavior of the API clients by creating a custom configuration This lets you change timeouts, or add HTTP headers.

To modify all requests made with a client, create a custom configuration. To modify individual requests, pass custom request options.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

Use a custom host

You can change the default hosts to which the API client connects:

1
2
3
4
5
6
7
8
val client =
    ClientSearch(
        ConfigurationSearch(
            applicationID = ApplicationID("YourApplicationID"),
            apiKey = APIKey("YourWriteAPIKey"),
            hosts = listOf(RetryableHost("yourapplication.example.net"))
        )
    )

Changing the hosts can be useful if you want to proxy the search requests through another server, for example, to process the request or response, or to perform custom analytics.

Add HTTP headers to every request

Adding HTTP headers to your configuration allow you to set parameters for every request, for example, a user identifier or an IP address. This can be useful for analytics, geo search, or to implement API key rate limits.

For an overview of available HTTP headers, see Add HTTP headers to your requests

1
2
3
4
5
6
val configuration = ConfigurationSearch(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourWriteAPIKey"),
    defaultHeaders = mapOf("NAME-OF-HEADER" to "value-of-header")
)
ClientSearch(configuration)

Change timeouts for all requests

Network connections and DNS resolution can be slow. That’s why the API clients come with default timeouts.

You shouldn’t change the default timeouts, unless you have a good reason.

1
2
3
4
5
6
7
val configuration = ConfigurationSearch(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourWriteAPIKey"),
    readTimeout = 50, // read timeout in seconds
    writeTimeout = 30 // write timeout in seconds
)
ClientSearch(configuration)

Select an HTTP client

The Kotlin API client relies on Ktor for its HTTP layer. Ktor lets you choose and configure the underlying HTTP engine.

See Engines in the Ktor documentation for a list of all supported HTTP engines.

If you don’t explicitly specify a HTTP engine, Ktor selects one for you, depending on which dependencies you installed.

Apache

1
implementation "io.ktor:ktor-client-apache:$ktor_version"
1
2
3
4
5
6
7
8
9
ClientSearch(
    ConfigurationSearch(
        applicationID = ApplicationID("Your Application ID"),
        apiKey = APIKey("Your API key"),
        engine = Apache.create {
            // Pass additional configuration here.
        }
    )
)

OkHttp

1
implementation "io.ktor:ktor-client-okhttp:$ktor_version"
1
2
3
4
5
6
7
8
9
ClientSearch(
    ConfigurationSearch(
        applicationID = ApplicationID("Your Application ID"),
        apiKey = APIKey("Your API key"),
        engine = OkHttp.create {
            // Pass additional configuration here.
        }
    )
)

Android HttpUrlConnection

1
implementation "io.ktor:ktor-client-android:$ktor_version"
1
2
3
4
5
6
7
8
9
ClientSearch(
    ConfigurationSearch(
        applicationID = ApplicationID("Your Application ID"),
        apiKey = APIKey("Your API key"),
        engine = Android.create {
            // Pass additional configuration here.
        }
    )
)
Did you find this page helpful?