Migration guide to version 2.x

Anthony Seure edited this page Jun 1, 2016 · 5 revisions

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.