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());

Configuration forwarding to the ingestion transporter

To use the WithTransformation helper methods, you must set the transformation region on the search client. This creates an internal ingestion transporter that handles requests to the transformation pipeline.

Each language forwards different configuration options from the search client to this transporter.

JavaScript

The JavaScript client spreads the full options object to the ingestion transporter. This includes appId, apiKey, region, hosts, timeouts, headers, compression, user agent, custom requester, caches, and query parameters.

Java

The Java client passes the full ClientOptions object to the ingestion transporter. This includes appId, apiKey, region, hosts, timeouts, headers, compression, user agent, custom requester, and query parameters.

C#

The C# client explicitly copies appId, apiKey, region, hosts, timeouts (ConnectTimeout, ReadTimeout, WriteTimeout), headers (DefaultHeaders), and compression to the ingestion transporter. User agent, custom requester, and query parameters aren’t forwarded.

PHP

The PHP client forwards appId, apiKey, region, and hosts to the ingestion transporter. Timeouts, headers, compression, and other options aren’t forwarded.

Python

The Python client forwards appId, apiKey, region, and hosts to the ingestion transporter. Timeouts, headers, compression, and other options aren’t forwarded.

Go

The Go client forwards appId, apiKey, region, and hosts to the ingestion transporter. Timeouts, headers, compression, and other options aren’t forwarded.

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");