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.

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

java
import com.algolia.model.search.*;
import com.algolia.utils.RequestOptions;
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForHits(
      new SearchForHits()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setHitsPerPage(50)
    )
  ),
  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.ofSearchForHits(
      new SearchForHits()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setHitsPerPage(50)
    )
  ),
  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 '@experimental-api-clients-automation/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 '@experimental-api-clients-automation/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

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>",
  ClientOptions.build().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>",
  ClientOptions.build().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 '@experimental-api-clients-automation/client-search';
import { echoRequester } from '@experimental-api-clients-automation/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 '@experimental-api-clients-automation/client-search';
import { echoRequester } from '@experimental-api-clients-automation/requester-node-http';
const client = searchClient('<YOUR_APP_ID>', '<YOUR_API_KEY>', {
  // The first parameter is the status to return
  requester: echoRequester(200),
});

PHP

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>",
  ClientOptions.build().setRequester(new MyOwnRequester())
);

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