API Reference
/
API Methods
/
Upgrade guides for the API client
Feb. 17, 2021
Upgrade guides for the API client
Upgrade to v3
The Java client is fully rebuilt while keeping a similar design to make it as smooth as possible to upgrade.
The client and index class have been renamed SearchClient and SearchIndex. The method names remain the same.
To have all the asynchronous and synchronous methods in the same place, the asynchronous client is now part of the SearchClient.
The Analytics and Insights clients use the same API design.
This new version is compatible with Java 8 and higher.
Estimated upgrade time: 1 hour.
This new version removes all deprecated methods and features from v2.
Upgrading the library
The library now comes in two parts.
algoliasearch-corewhich holds all the methods, the POJOs, the transport layer and the retry strategy. This jar is agnostic of any HTTP client implementation.algoliasearch-apachewhich is the default HTTP client implementation for the core library.
Upgrade with Maven
Add the following code in your pom.xml:
Copy
1
2
3
4
5
6
7
8
9
10
11
<dependency>
<groupId>com.algolia</groupId>
<artifactId>algoliasearch-core</artifactId>
<version>3.6.1</version>
</dependency>
<dependency>
<groupId>com.algolia</groupId>
<artifactId>algoliasearch-apache</artifactId>
<version>3.6.1</version>
</dependency>
Upgrade with Gradle
Add the following code in your build.gradle:
Copy
1
2
compile 'com.algolia:algoliasearch-core:3.+'
compile 'com.algolia:algoliasearch-apache:3.+'
Client instantiation
Replace the instantiation of the client as shown below.
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Before
APIClient client =
new ApacheAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();
Index<Contact> index = client.initIndex("your_index_name", Contact.class);
AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();
AsyncIndex<Contact> index = client.initIndex("your_index_name", Contact.class);
// After
// It's the same class for async and sync methods!
SearchClient client =
DefaultSearchClient.create("YourApplicationID", "YourAdminAPIKey");
SearchIndex<Contact> index = client.initIndex("your_index_name", Contact.class);
Instantiate with configuration
You can instantiate all clients via a configuration builder. This is useful to affect the way a client behaves.
You can configure :
- DefaultHeaders: to set HTTP headers for every request
- BatchSize: to customize the chunk size of batches for save methods
- Hosts: to set custom hosts to target
- Timeouts : to set timeout such as the read timeout, the write timeout, and the connect timeout
- ExecutorService: to set your own
ExecutorService
Example:
Copy
1
2
3
4
5
6
7
8
9
10
11
SearchConfig config =
new SearchConfig.Builder("YourApplicationID", "YourAdminAPIKey")
.setHosts(...)
.setReadTimeOut(...)
.setWriteTimeOut(...)
.setConnectTimeOut(...)
.setBatchSize(...)
.setExecutorService(...)
.build();
SearchClient client = DefaultSearchClient.create(config);
Analytics instantiation
Similarly, you need to update the way you initialize the Analytics client.
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Before
APIClient client =
new ApacheAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();
Analytics analytics = client.initAnalytics();
AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();
AsyncAnalytics analytics = client.initAnalytics();
// After
// It's the same class for async and sync methods!
AnalyticsClient analytics =
DefaultAnalyticsClient.create("YourApplicationID", "YourAdminAPIKey");
Insights instantiation
You need to update the way you initialize the Insights client:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Before
APIClient client =
new ApacheAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();
SyncInsightsClient insights =
new SyncInsightsClient("YourApplicationID", "YourAdminAPIKey", client)
AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();
AsyncInsightsClient insights =
new AsyncInsightsClient("YourApplicationID", "YourAdminAPIKey", client)
// After
// It's the same class for async and sync methods!
InsightsClient insights =
DefaultInsightsClient.create("YourApplicationID", "YourAdminAPIKey");
Breaking changes
To ease the update, most of the POJOs didn’t change. There are some breaking changes you can find in the following table.
All methods marked as @Depracted are removed.
Clients
| Methods/Features in v2.x | Breaking Change | Methods/Features in v3.x |
|---|---|---|
APIClient | Removed. Use SearchClient AnalyticsClient InsightsClient instead. | DefaultSearchClient.create(..) DefaultAnalyticsClient.create(..) DefaultInsightsClient.create(..) |
AsyncAPIClient | Removed. Use SearchClient AnalyticsClient InsightsClient instead. | DefaultSearchClient.create(..) DefaultAnalyticsClient.create(..) DefaultInsightsClient.create(..) |
SearchClient
| Methods/Features in v2.x | Breaking Change | Methods/Features in v3.x |
|---|---|---|
listKeys() | Removed. Use listApiKeys() instead. | listApiKeys() |
Index/SearchIndex
| Methods/Features in v2.x | Breaking Change | Methods/Features in v3.x |
|---|---|---|
deleteByQuery(query) | Removed. Use deleteBy() instead. | deleteBy(query) |
searchInFacetValues(facetName,facetQuery,query) | Removed. Use searchForFacetValues() instead. | searchForFacetValues(String, String, Query) |
index.browse(Query) | Breaking | index.browseObjects(BrowseIndexQuery) |
BrowseResult<T> | Breaking | BrowseIndexResponse<T> |
IndexSetting.getAttributesToIndex() | Removed. Use searchableAttributes instead. | IndexSetting.getSearchableAttributes() |
IndexSetting.setAttributesToIndex() | Removed. Use searchableAttributes instead. | IndexSetting.setSearchableAttributes() |
Query.setFacetFilters(List<String>) | Breaking | Query.setFacetFilters(List<List<String>>) |
Query.setNumericFilters(List<String>) | Breaking | Query.setNumericFilters(List<List<String>>) |
Query.setTagFilters(List<String>) | Breaking | Query.setTagFilters(List<List<String>>) |
Query.setOptionalFilters(List<String>) | Breaking | Query.setOptionalFilters(List<List<String>>) |
AbstractSynonym | Removed use Synonym instead. | Synonym |
ConsequenceQueryObject | Removed. Use ConsequenceQuery instead. | ConsequenceQuery |
ConsequenceQueryObject.setRemove(List<String>) | Removed. Use ConsequenceQuery.setEdits() instead. | ConsequenceQuery.setEdits(List<Edits>>) |
AnalyticsClient
| Methods/Features in v2.x | Breaking Change | Methods/Features in v3.x |
|---|---|---|
TaskABTest addABTest(ABTest abtest) | Breaking | AddABTestResponse addABTest(ABTest abTest) |
TaskABTest stopABTest(long id) | Breaking. | StopAbTestResponse stopABTest(long id) |
TaskABTest deleteABTest(long id) | Breaking. | DeleteAbTestResponse deleteABTest(long id) |
ABTest getABTest(long id) | Breaking. | ABTestResponse getABTest(long id) |
