Migration guide from 1.x to 2.x

Overview

The 2nd version of the Go client is introduced to improve type safety, testability and maintainability. With all those improvements come incompatible changes with the first version of the client. This document is intended to the users of the v1.x of the client who choose to migrate their code from version 1.x to 2.x.

Non-backward compatible changes are affecting all the existing functions from the Index and Client code, bringing new types for every response from the Algolia API instead of interface{} or map[string]interface{}. Parameters are also typed now and are checked as much as possible.

The Client and Index are now interfaces while their respective implementation are described by the client and index structures. This way, users can now mock the Client and the Index for their own testing purpose.

Index changes

Changed methods (33)

Method	Parameter(s)	Return value(s)
Delete	-	Typed result (DeleteTaskRes)
Clear	-	Typed result (UpdateTaskRes)
GetObject	attributes is now a slice instead of a variadic parameter	Typed result (Object)
GetObjects	objectIDs is now a slice instead of a variadic parameter	Typed result ([]Object)
DeleteObject	-	Typed result (DeleteTaskRes)
GetSettings	-	Typed result (Settings)
SetSettings	settings is now a Map instead of a interface{}	Typed result (UpdateTaskRes)
WaitTask	The parameter is now the taskID integer instead of an interface{} hiding a float or a map containing a taskID field Only returns an error if the task hasn’t finished properly
ListKeys	-	Typed result ([]Keys)
AddUserKey (previously named AddKey)	Still takes the ACL as a slice of string but all the other parameters have to be passed in a Map	Typed result (AddKeyRes)
UpdateUserKey (previously named UpdateKey)	Only takes the key string value and all the other parameters have to be passed in a Map	Typed result (UpdateKeyRes)
GetUserKey (previously named GetKey)	-	Typed result (Key)
DeleteUserKey (previously named DeleteKey)	-	Typed result (DeleteRes)
AddObject	object in now typed as an Object (Map)	Typed result (CreateObjectRes)
UpdateObject	object is now typed as an Object which must contains the objectID value	Typed result (UpdateObjectRes)
PartialUpdateObject	object is now typed as an Object which must contains the objectID value	Typed result (UpdateTaskRes)
AddObjects	objects is now a slice of Object instead of an interface	Typed result (BatchRes)
UpdateObjects	objects is now a slice of Object instead of an interface	Typed result (BatchRes)
PartialUpdateObjects	objects is now a slice of Object instead of an interface	Typed result (BatchRes)
DeleteObjects	-	Typed result (BatchRes)
Batch	Takes a slice of BatchOperation instead of two different slices containing the objects and their associated action	Typed result (BatchRes)
Copy	-	Typed result (UpdateTaskRes)
Move	-	Typed result (UpdateTaskRes)
SearchSynonyms	-	Typed result ([]Synonym)
GetSynonym	-	Typed result (Synonym)
AddSynonym (previously named SaveSynonym)	Same parameters except the synonym itself which becomes a Synonym type instead of an interface{}	Typed result (UpdateTaskRes)
DeleteSynonym	-	Typed result (DeleteTaskRes)
ClearSynonyms	-	Typed result (UpdateTaskRes)
BatchSynonyms	Same parameters except the synonyms itself which becomes a []Synonym instead of a []interface{}	Typed result (UpdateTaskRes)
Browse	Only takes one Map containing all the parameters	Typed result (BrowseRes)
BrowseAll	params is now a Map instead of an interface{} Returns an IndexIterator interface instead of a *IndexIterator (v1 implementation)
Search	params is now a Map instead of an interface{}	Typed result (QueryRes)
DeleteByQuery	params is now a Map instead of an map[string]interface{}.	Only returns an error because it now hangs until the deletion of all the matching records, there's no need to call WaitTask after it.

Added methods (1)

Method	Note
GetStatus	Use it to retrieve the status of a task. This method was previously unexported but we decided to change that because it may help the user to have a better control on the running tasks, especially since the TaskID field is present in nearly each response.

Removed methods (2)

Method	Note
BrowseFrom	This method was used to browse the index after a first call to the Browse method, used to retrieve the browsing cursor. We felt that it was too complicated and merged it with the new Browse method. Now, the Browse method does the same as before when passing an empty string as a cursor and does the job of the previous BrowseFrom otherwise.
CustomBatch	CustomBatch was internally used by the Batch method. It was useless to keep two (exported) methods to do nearly the same job. Now, there’s only the Batch method to perform batched operations.

Client changes

Changed methods (13)

Method	Parameter(s)	Return value(s)
ListIndexes	-	Typed result ([]IndexRes)
InitIndex	-	Returns an Index interface instead of a *Index (v1 implementation)
ListKeys	-	Typed result ([]Key)
MoveIndex	-	Typed result (UpdateTaskRes)
CopyIndex	-	Typed result (UpdateTaskRes)
AddUserKey (previously named AddKey)	Still takes the ACL as a slice of string but all the other parameters have to be passed in a Map	Typed result (AddKeyRes)
UpdateUserKey (previously named UpdateKey)	Only takes the key string value and all the other parameters have to be passed in a Map	Typed result (UpdateKeyRes)
GetUserKey (previously named GetKey)	-	Typed result (Key)
DeleteUserKey (previously named DeleteKey)	-	Typed result (DeleteKey)
GetLogs	Parameters are required to be passed in a Map	Typed result ([]LogRes)
GenerateSecuredAPIKey	Parameters previously passed as public and userToken are now passed in a single Map.	-
MultipleQueries	Now expect queries as a []IndexedQuery and the strategy string	Typed result ([]MultipleQueryRes)
Batch (previously named CustomBatch)	Typed parameter ([]BatchOperationIndexed)	Typed result (MultipleBatchRes)

Added methods (2)

Method	Note
DeleteIndex	Method used to delete an index according to its name
ClearIndex	Method used to clear an index according to its name

Removed methods (3)

Method	Note
AddKeyWithParam	Previously, AddKey was a wrapper of AddKeyWithParam. We simplify the implementation in order to have only one method to add a key.
UpdateKeyWithParam	Previously, UpdateKey was a wrapper of UpdateKeyWithParam. We simplify the implementation in order to have only one method to update a key.
EncodeParams	This method was only here to internally escape URL. Since it was only calling url.QueryEscape from the Transport, we removed it and replaced each call to QueryEscape directly.

Index changes

Changed methods (0)

None

Added methods (0)

None

Removed methods (1)

Method	Note
EncodeParams	This method was only here to internally escape URL. Since it was only calling url.QueryEscape, we removed it and replaced each call to QueryEscape directly.