API Reference / API Methods / Upgrade guides for the API client
Feb. 07, 2019

Upgrade guides for the API client

Upgrade to v6

We entirely rewrote the .NET client but we chose to keep a similar design to make it as easy as possible to upgrade.

There is still a client and an index class but they have been renamed to SearchClient and SearchIndex with similar method names.

This new version is compatible with the same .NET versions as before (from .NET 4.5 to .NET Core 2.2)

Upgrading the Library

With the .NET CLI

1
dotnet add package Algolia.Search

With the Nuget Package Manager Console

1
Update-Package Algolia.Search

With Nuget.org

Download the package on Nuget.org.

Client Instantiation

Replace the instantiation of the client as shown below.

1
2
3
4
5
6
7
// Before
AlgoliaClient client = new AlgoliaClient("YourApplicationID", "YourAPIKey");
Index index = client.InitIndex("your_index_name");

// After
SearchClient client = new SearchClient("YourApplicationID", "YourAPIKey");
SearchIndex index = client.InitIndex("your_index_name");

Using configuration

All clients can be instantiated via configuration objects. 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 size of batch for save methods
  • Hosts to set custom hosts

Example:

1
2
3
4
5
6
7
8
9
10
SearchConfig config = new SearchConfig("YourApplicationId", "YourAdminAPIKey")
{
  BatchSize = 2000,
  DefaultHeaders = new Dictionary<string, string>
  {
    { "MyCustomerHeaderKey", "MyCustomerHeaderValue" }
  }
};

SearchClient client = new SearchClient(config);

Analytics Instantiation

Similarly, you need to update the way you initialize the Analytics client.

1
2
3
4
5
6
// Before
AlgoliaClient client = new AlgoliaClient("YourApplicationID", "YourAPIKey");
Analytics analytics = new Analytics(client);

// After
AnalyticsClient analytics = new AnalyticsClient("YourApplicationID", "YourAPIKey";

New Methods

Some new methods were added to help implement some commonly used features. These features were always available but required either a deeper understanding or custom code.

  • CopySettings: Allows you to copy settings between indices.
  • CopySynonyms: Allows you to copy synonyms between indices.
  • CopyRules: Allows you to copy rules between indices.
  • ReplaceAllObjects: Allows you to add new objects to an index and remove all existing ones, atomically.
  • ReplaceAllSynonyms: Allows you to add new synonyms to an index and remove all existing ones, atomically.
  • ReplaceAllRules: Allows you to add new rules to an index and remove all existing ones, atomically.
  • AccountClient.CopyIndex: Allows you to copy an index between Algolia applications. Very handy when doing client work.
  • CustomRequest: Allows you to request the Algolia API with custom parameters, URI, and headers.

Breaking Changes

JObject and types

The v6 of the client, in contrast to the previous one, is Typed for every method. This implies a breaking change on almost all methods. You can still save and retrieve your records with JObject. However, regarding Settings, Rules, APIkeys, and Synonyms, you will have to convert your JObject to a class.

How to export JObject to new types

Example with settings :

1
2
3
4
// Your old JObject
JObject oldObject = JObject.Parse("{\"customRanking\":[\"desc(population)\", \"asc(name)\"], \"attributesToIndex\":[\"attr1\", \"attr2\"],\"numericAttributesToIndex\": [\"attr1\", \"attr2\"]}");

IndexSettings settings = oldObject.ToObject<IndexSettings>();

This snippet also works for all other classes in the client as Rules, APIkeys, Synonyms, etc.

List of Method Changes

Before After
SetSettings(settings, null, true) SetSettings(settings, forwardToReplicas: true)
BatchSynonyms(synonyms, true, false) SaveSynonyms(synonyms, forwardToReplicas: true)
BatchSynonyms(synonyms, true, true) ReplaceAllSynonyms(synonyms, forwardToReplicas: true)
BatchSynonyms(synonyms, false, false) SaveSynonyms(synonyms)
BatchSynonyms(synonyms, false, true) ReplaceAllSynonyms(synonyms)
AddObjects(objectsWithObjectId) SaveObjects(objectsWithObjectId)
AddObjects(objectsWithoutObjectId) SaveObjects(objectsWithoutObjectId, autoGenerateObjectId: true)

List of Return Type Changes

AlgoliaClient/SearchClient

Method name New return type Old return type
InitIndex SearchIndexIndex
MultipleGetObjects MultipleGetObjectsResponse< T >JObject
MultipleQueries MultipleQueriesResponse< T >JObject
MultipleBatch MultipleIndexBatchIndexingResponseJObject
ListIndices ListIndicesResponseJObject
DeleteIndex DeleteResponseJObject
ListApiKeys ListApiKeysResponseJObject
GetApiKey ApiKeyJObject
AddApiKey AddApiKeyResponseJObject
UpdateApiKey UpdateApiKeyResponseJObject
DeleteApiKey DeleteApiKeyResponseJObject
ListClusters IEnumerable< ClustersResponse >JObject
SearchUserIDs SearchResponse< UserIdResponse >JObject
ListUserIds ListUserIdsResponseJObject
GetUserId UserIdResponseJObject
GetTopUserId TopUserIdResponseJObject
AssignUserId AssignUserIdResponseJObject
RemoveUserId RemoveUserIdResponseJObject
GetLogs LogResponseJObject
CopySettings CopyToResponseJObject
CopyRules CopyToResponseJObject
CopySynonyms CopyToResponseJObject
CopyIndex CopyToResponseJObject
MoveIndex MoveIndexResponseJObject

AlgoliaClient/AnalyticsClient

Method name New return type Old return type
GetABTest ABTestJObject
GetABTests ABTestsReponseJObject
AddABTest AddABTestResponseJObject
StopABTest StopABTestResponseJObject
DeleteABTest DeleteABTestResponseJObject

Index/SearchIndex

Method name New return type Old return type
PartialUpdateObject UpdateObjectResponseJObject
PartialUpdateObjects BatchIndexingResponseJObject
SaveObject BatchIndexingResponseJObject
SaveObjects BatchIndexingResponseJObject
ReplaceAllObjects MultiResponseJObject
Batch BatchResponseJObject
Batch BatchResponseJObject
DeleteObject DeleteResponseJObject
DeleteObjects BatchIndexingResponseJObject
DeleteBy DeleteResponseJObject
ClearObjects DeleteResponseJObject
Search SearchResponse< T >JObject
SearchForFacetValue SearchForFacetResponseJObject
GetObject TJObject
GetObjects IEnumerable< T >JObject
Browse IndexIterator< T >JObject
BrowseFrom BrowseIndexResponse< T >JObject
GetRule RuleJObject
SearchRule SearchResponse< Rule >JObject
SaveRule SaveRuleResponseJObject
SaveRules BatchResponseJObject
ReplaceAllRules BatchResponseJObject
DeleteRule DeleteResponseJObject
ClearRules DeleteResponseJObject
GetSettings IndexSettingsJObject
SetSettings SetSettingsResponseJObject
SearchSynonyms SearchResponse< Synonym >JObject
GetSynonym SynonymJObject
SaveSynonyms SaveSynonymResponseJObject
ReplaceAllSynonyms SaveSynonymResponseJObject
SaveSynonym SaveSynonymResponseJObject
DeleteSynonym DeleteResponseJObject
ClearSynonyms ClearSynonymsResponseJObject
CopyTo CopyToResponseJObject
MoveFrom MoveIndexResponseJObject
WaitTask VoidJObject
GetTask TaskStatusResponseJObject

Did you find this page helpful?