Customize the API clients

Customize your API clients to tailor request logging, timeouts, user agent information, headers, and hosts for flexible integrations.

To change the settings for all requests, you can initialize the API client with a custom configuration.

To configure individual requests, see Request options.

Not all API clients support all customization options.

Custom configuration

Customize the API client by creating a configuration object or by passing additional options when instantiating the client.

C#

using Algolia.Search.Clients;

// Create custom configuration
var config = new SearchConfig(
    appId: "ALGOLIA_APPLICATION_ID",
    apiKey: "ALGOLIA_API_KEY"
);

// Customize the configuration ...

// Instantiate SearchClient with custom configuration
var client = new SearchClient(config);

Adjust timeouts

The following example shows how to adjust the default timeouts for all requests.

C#

// ...
config.ReadTimeout = TimeSpan.FromSeconds(100);
config.WriteTimeout = TimeSpan.FromSeconds(100);
config.ConnectTimeout = TimeSpan.FromSeconds(100);
// ...

For more information about these timeouts, see Request options.

Customize user agent information

The following example shows how to add a custom user agent string to the default.

C#

// ...
config.UserAgent.AddSegment("custom c# client", "optional version");
// ...

Add default headers

The following example shows how to add a custom header to all API requests.

C#

// ...
config.DefaultHeaders.Add("extra-header", "greetings");
// ...

If you use the JavaScript API client in a browser — including when you use InstantSearch or Autocomplete, which rely on the API client — you can’t send arbitrary HTTP headers.

Browsers enforce cross-origin resource sharing (CORS) rules. During the OPTIONS preflight request, the API explicitly lists which headers it accepts in the access-control-allow-headers response header. Any header not listed there is blocked by the browser.

To see which headers are allowed, check the access-control-allow-headers value in the preflight response in your browser’s developer tools.

Logging

You can set a custom logger to enable more or less logging output.

C#

using Algolia.Search.Clients;
// Install with `dotnet add package Microsoft.Extensions.Logging.Console`
using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
{
    // Log everything from Algolia in the console, including debug logs
    builder.AddFilter("Algolia", LogLevel.Debug).AddConsole();
});

var client = new SearchClient(
    "ALGOLIA_APPLICATION_ID",
    "ALGOLIA_API_KEY",
    loggerFactory,
);

Custom hosts

The following example shows how to add your own servers.

JavaScript

// ...
const options = {
  hosts: [
    {
      // URL of your server without scheme
      url: "YOUR_SERVER_URL",
      // Whether this server can be used for read, write, or both requests
      accept: "readWrite", // read | write | readWrite
      // https or http
      protocol: "https",
      // Optional, if deviating from the default port
      // port: "PORT"
    },
  ],
};
// ...

Custom HTTP clients

The following example shows how to use a custom HTTP client to make requests.

C#

using Algolia.Search.Clients;

var config = new SearchConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// CustomRequester must implement `IHTTPRequester`
var client = new SearchClient(config, new CustomRequester());

DNS caching (Java)

By default, the JVM caches DNS resolutions infinitely. Since Algolia uses multiple IP addresses for load balancing, you should reduce the time to live (TTL) of the cache.

For example, set the TTL of the cache to 60 seconds:

Java

java.security.Security.setProperty("networkaddress.cache.ttl", "60");