Migration guide to version 4.x

Overview

The main purpose of version 4 is to support Swift 3 (#74). It was also the opportunity to improve the “look and feel” of the library. Apart from that, no new major features were introduced.

Note: Since the Swift API Client is distributed in source form, in order to user version 4, you need to adopt Swift 3 in your own project.

Objective-C bridging has been revised (and, we hope, improved):

• The Query class as seen from Swift no longer uses suboptimal types like NSNumber. As a consequence, the infamous underscore-suffixed properties are no longer necessary. You can enjoy clean auto-completion:

… compared to the previous situation:

Note: Seen from Objective-C, the Query class still contains all properties with Objective-C compatible types (as before).

• Method names in Objective-C have been remapped to feel more natural (see below).

Changes

Note: Most changes are just a side effect of complying with the Swift API Design Guidelines, especially regarding argument labeling and using lower camel case for anything else but type (class and protocol) names.

Here is a detailed list of changes:

Common

Class Client:

• Constant ErrorDomain removed. Error handling now uses dedicated error types: HTTPError and InvalidJSONError
• Properties timeout and searchTimeout are now writable
• Method setHeader(_:value:) renamed to setHeader(withName:to:)
• Method getHeader(_:) renamed to header(withName:)
• Method getIndex(_:) renamed to index(withName:)
  • Also, Index instances are now shared among a given Client
• Method deleteIndex(_:completionHandler:) renamed to deleteIndex(withName:completionHandler:)
• Method moveIndex(_:to:completionHandler:) renamed to moveIndex(from:to:completionHandler:)
• Method copyIndex(_:to:completionHandler:) renamed to copyIndex(from:to:completionHandler:)
• Method batch(_:completionHandler:) renamed to batch(operations;completionHandler:)
• Method isAlive(_:) renamed to isAlive(completionHandler:)

Class Index:

• Property indexName renamed to name
• Method deleteObject(_:completionHandler:) renamed to deleteObject(withID:completionHandler:)
• Method deleteObjects(_:completionHandler:) renamed to deleteObjects(withIDs:completionHandler:)
• Method getObject(_:completionHandler:) renamed to getObject(withID:completionHandler:)
• Method getObject(_:attributesToRetrieve:completionHandler:) renamed to getObject(withID:attributesToRetrieve:completionHandler:)
• Method getObjects(_:completionHandler:) renamed to getObjects(withIDs:completionHandler:)
• Method getObjects(_:attributesToRetrieve:completionHandler:) renamed to getObjects(withIDs:attributesToRetrieve:completionHandler:)
• Method partialUpdateObject(_:objectID:completionHandler:) renamed to partialUpdateObject(_:withID:completionHandler:)
• Method getSettings(_:) renamed to getSettings(completionHandler:)
• Method setSettings(_:forwardToSlaves:completionHandler:) renamed to setSettings(_:forwardToReplicas:completionHandler:)
• Method clearIndex(_:) renamed to clearIndex(completionHandler:)
• Method batch(_:completionHandler:) renamed to batch(operations:completionHandler:)
• Method browse(_:completionHandler:) renamed to browse(query:completionHandler:)
• Method browseFrom(_:completionHandler:) renamed to browse(from:completionHandler:)
• Method waitTask(_:completionHandler:) renamed to waitTask(withID:completionHandler:)
• Methods enableSearchCache(_:) and disableSearchCache() replaced by two properties:
  • searchCacheEnabled
  • searchCacheExpiringTimeInterval

Offline mode

Class MirroredIndex:

• Constants now lower camel case
  • … except notification names (which in theory contradicts the Swift API Design Guidelines, but the system APIs follow the same convention)
• Notification names now typed Notification.Name (NSNotificationName in Objective-C)
• Method browseMirror(_:completionHandler:) renamed to browseMirror(query:completionHandler:)
• Method browseMirrorFrom(_:completionHandler:) renamed to browseMirror(from:completionHandler:)
• Enum Strategy now uses lower camel case for members

Class OfflineClient:

• Method enableOfflineMode(_:) renamed to enableOfflineMode(licenseKey:)

Swift-specific

Class Query:

• Enums AlternativesAsExact, AroundRadius, ExactOnSingleWordQuery, QueryType, RemoveStopWords, RemoveWordsIfNoResults and TypoTolerance now use lower camel case for their members
• Method get(_:) renamed to parameter(withName:)
• Method set(_:value:) renamed to setParameter(withName:to:)
• Property queryType now enum-typed, property queryType_ removed
• Property typoTolerance now enum-typed, property typoTolerance_ removed
• Property minWordSizefor1Typo now typed UInt?
• Property minWordSizefor2Typos now typed UInt?
• Property allowTyposOnNumericTokens now typed Bool?
• Property ignorePlurals now typed Bool?
• Property advancedSyntax now typed Bool?
• Property analytics now typed Bool?
• Property synonyms now typed Bool?
• Property replaceSynonymsInHighlight now typed Bool?
• Property minProximity now typed UInt?
• Property removeWordsIfNoResults now enum-typed, property removeWordsIfNoResults_ removed
• Property removeStopWords now enum-typed
• Property exactOnSingleWordQuery now enum-typed, property exactOnSingleWordQuery_ removed
• Property alternativesAsExact now enum-typed, property alternativesAsExact_ removed
• Property page now typed UInt?
• Property hitsPerPage now typed UInt?
• Property getRankingInfo now typed Bool?
• Property distinct now typed UInt?
• Property maxValuesPerFacet now typed UInt?
• Property aroundLatLngViaIP now typed Bool?
• Property aroundRadius now enum-typed
• Property aroundPrecision now typed UInt?
• Property minimumAroundRadius now typed UInt?

Objective-C-specific

• browse(from:completionHandler:) is mapped to browseFromCursor:completionHandler:
• batch(operations:completionHandler:) is mapped to batchOperations:completionHandler: