Customized client usage

You might want to customize how the API client works, by providing additional information to your request, adding user-agents or use your own HTTP requester.

Setting a logger

You can set a custom logger on the client to enable more or less debug output depending on your need.

JavaScript

java
import com.algolia.api.SearchClient;
import com.algolia.utils.LogLevel;
SearchClient client = new SearchClient("<YOUR_INDEX_NAME>", "<YOUR_API_KEY>");
// No logs.
client.setLogLevel(LogLevel.NONE);
// Logs request and response lines.
client.setLogLevel(LogLevel.BASIC);
// Logs request and response lines and their respective headers.
client.setLogLevel(LogLevel.HEADERS);
// Logs request and response lines and their respective headers and bodies (if present).
client.setLogLevel(LogLevel.BODY);

java
import com.algolia.api.SearchClient;
import com.algolia.utils.LogLevel;
SearchClient client = new SearchClient("<YOUR_INDEX_NAME>", "<YOUR_API_KEY>");
// No logs.
client.setLogLevel(LogLevel.NONE);
// Logs request and response lines.
client.setLogLevel(LogLevel.BASIC);
// Logs request and response lines and their respective headers.
client.setLogLevel(LogLevel.HEADERS);
// Logs request and response lines and their respective headers and bodies (if present).
client.setLogLevel(LogLevel.BODY);

Send additional information in your request with requestOptions

The requestOptions parameter allows you to merge additional information with the client transporter, such as headers or query parameters.

Note: requestOptions overrides the default parameters that were previously set in the method and client.

JavaScript

js
await client.search(
  {
    requests: [
      {
        indexName: '<YOUR_INDEX_NAME>',
        query: '<YOUR_QUERY>',
        hitsPerPage: 50,
      },
    ],
  },
  {
    // This header is added to the request
    headers: {
      'additional-header': 'hello',
    },
    // As we re-define `hitsPerPage`, it will override the value defined in the method's parameters.
    queryParameters: {
      hitsPerPage: 100,
    },
  }
);

js
await client.search(
  {
    requests: [
      {
        indexName: '<YOUR_INDEX_NAME>',
        query: '<YOUR_QUERY>',
        hitsPerPage: 50,
      },
    ],
  },
  {
    // This header is added to the request
    headers: {
      'additional-header': 'hello',
    },
    // As we re-define `hitsPerPage`, it will override the value defined in the method's parameters.
    queryParameters: {
      hitsPerPage: 100,
    },
  }
);

PHP

php
$client->search(
    [
        'requests' => [
            [
                'indexName' => '<YOUR_INDEX_NAME>',
                'query' => '<YOUR_QUERY>',
                'hitsPerPage' => 50,
            ],
        ]
    ],
    [
        // This header is added to the request
        'headers' => ['additional-header' => 'hello'],
        // As we re-define `hitsPerPage`, it will override the value defined in the method's parameters.
        'queryParameters' => ['hitsPerPage' => 100],
    ]
);

php
$client->search(
    [
        'requests' => [
            [
                'indexName' => '<YOUR_INDEX_NAME>',
                'query' => '<YOUR_QUERY>',
                'hitsPerPage' => 50,
            ],
        ]
    ],
    [
        // This header is added to the request
        'headers' => ['additional-header' => 'hello'],
        // As we re-define `hitsPerPage`, it will override the value defined in the method's parameters.
        'queryParameters' => ['hitsPerPage' => 100],
    ]
);

Java

java
import com.algolia.model.search.*;
import com.algolia.utils.RequestOptions;
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.of(
      new SearchForHits()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setHitsPerPage(50)
    )
  ),
  MyObject.class,
  new RequestOptions()
    // This header is added to the request
    .addExtraHeader("additional-header", "hello")
    // As we re-define `hitsPerPage`, it will override the value defined in the method's parameters.
    .addExtraQueryParameters("hitsPerPage", 100)
);

java
import com.algolia.model.search.*;
import com.algolia.utils.RequestOptions;
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.of(
      new SearchForHits()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setHitsPerPage(50)
    )
  ),
  MyObject.class,
  new RequestOptions()
    // This header is added to the request
    .addExtraHeader("additional-header", "hello")
    // As we re-define `hitsPerPage`, it will override the value defined in the method's parameters.
    .addExtraQueryParameters("hitsPerPage", 100)
);

Provide your own user-agent

The API clients offers a method for you to append data to the current user-agent.

JavaScript

In the JavaScript client, user-agent are sent in the header via the x-algolia-agent property.

js
import { searchClient } from '@algolia/client-search';
const client = searchClient('<YOUR_APP_ID>', '<YOUR_API_KEY>');
// This will append `; my user agent (optional version)` to the current value of `x-algolia-agent` for every requests
client.addAlgoliaAgent('my user agent', 'optional version');

js
import { searchClient } from '@algolia/client-search';
const client = searchClient('<YOUR_APP_ID>', '<YOUR_API_KEY>');
// This will append `; my user agent (optional version)` to the current value of `x-algolia-agent` for every requests
client.addAlgoliaAgent('my user agent', 'optional version');

PHP

php
$client = SearchClient::create(
    '<YOUR_APP_ID>',
    '<YOUR_APP_ID>'
);
// This will append `; my user agent (optional version)` to the current value of `User-Agent` for every requests
Algolia\AlgoliaSearch\Support\AlgoliaAgent::addAlgoliaAgent(
    $client->getClientConfig()->getClientName(),
    "my user agent",
    "optional version"
);

php
$client = SearchClient::create(
    '<YOUR_APP_ID>',
    '<YOUR_APP_ID>'
);
// This will append `; my user agent (optional version)` to the current value of `User-Agent` for every requests
Algolia\AlgoliaSearch\Support\AlgoliaAgent::addAlgoliaAgent(
    $client->getClientConfig()->getClientName(),
    "my user agent",
    "optional version"
);

Java

java
import com.algolia.utils.ClientOptions;
import com.algolia.api.SearchClient;
// This will append `; my user agent (optional version)` to the current value of `x-algolia-agent` for every requests
SearchClient client = new SearchClient(
  "<YOUR_APP_ID>",
  "<YOUR_API_KEY>",
  new ClientOptions().addAlgoliaAgentSegments("my user agent", "optional version")
);

java
import com.algolia.utils.ClientOptions;
import com.algolia.api.SearchClient;
// This will append `; my user agent (optional version)` to the current value of `x-algolia-agent` for every requests
SearchClient client = new SearchClient(
  "<YOUR_APP_ID>",
  "<YOUR_API_KEY>",
  new ClientOptions().addAlgoliaAgentSegments("my user agent", "optional version")
);

Use your own HTTP requester

You can override the default requester behavior by providing your requester logic at the initialization of the client.

JavaScript

The JavaScript client provides an echoRequester, that will return the full payload of the request.

js
import { searchClient } from '@algolia/client-search';
import { echoRequester } from '@algolia/requester-node-http';
const client = searchClient('<YOUR_APP_ID>', '<YOUR_API_KEY>', {
  // The first parameter is the status to return
  requester: echoRequester(200),
});

js
import { searchClient } from '@algolia/client-search';
import { echoRequester } from '@algolia/requester-node-http';
const client = searchClient('<YOUR_APP_ID>', '<YOUR_API_KEY>', {
  // The first parameter is the status to return
  requester: echoRequester(200),
});

PHP

In PHP, the requests are handled by the HTTP Client (by default GuzzleHttpClient)

php
use Algolia\AlgoliaSearch\Api\SearchClient;
use Algolia\AlgoliaSearch\Configuration\SearchConfig;
use Algolia\AlgoliaSearch\Http\HttpClientInterface;
use Algolia\AlgoliaSearch\RetryStrategy\ApiWrapper;
use Algolia\AlgoliaSearch\RetryStrategy\ClusterHosts;
// Create a config and a clusterhosts objects with your credentials
$config = SearchConfig::create('<YOUR_APP_ID>', '<YOUR_API_KEY>');
$clusterHosts = ClusterHosts::createFromAppId('<YOUR_APP_ID>');
// Instanciate a MyHttpClient object implementing HttpClientInterface (replacing GuzzleHttpClient)
$myHttpClient = new MyHttpClient(...);
// Now create you custom Api wrapper
$apiWrapper = new ApiWrapper($myHttpClient, $config, $clusterHosts);
// Instanciate your client using the constructor
$client = new SearchClient($apiWrapper, $config);

php
use Algolia\AlgoliaSearch\Api\SearchClient;
use Algolia\AlgoliaSearch\Configuration\SearchConfig;
use Algolia\AlgoliaSearch\Http\HttpClientInterface;
use Algolia\AlgoliaSearch\RetryStrategy\ApiWrapper;
use Algolia\AlgoliaSearch\RetryStrategy\ClusterHosts;
// Create a config and a clusterhosts objects with your credentials
$config = SearchConfig::create('<YOUR_APP_ID>', '<YOUR_API_KEY>');
$clusterHosts = ClusterHosts::createFromAppId('<YOUR_APP_ID>');
// Instanciate a MyHttpClient object implementing HttpClientInterface (replacing GuzzleHttpClient)
$myHttpClient = new MyHttpClient(...);
// Now create you custom Api wrapper
$apiWrapper = new ApiWrapper($myHttpClient, $config, $clusterHosts);
// Instanciate your client using the constructor
$client = new SearchClient($apiWrapper, $config);

Java

Create your own requester by creating a class that implements com.algolia.utils.Requester, and use it by passing it to the client constructor.

java
import com.algolia.api.SearchClient;
SearchClient client = new SearchClient(
  "<YOUR_APP_ID>",
  "<YOUR_API_KEY>",
  new ClientOptions().setRequester(new MyOwnRequester())
);

java
import com.algolia.api.SearchClient;
SearchClient client = new SearchClient(
  "<YOUR_APP_ID>",
  "<YOUR_API_KEY>",
  new ClientOptions().setRequester(new MyOwnRequester())
);