Migration guide to version 4.x

Overview

The main purpose of version 4 is support for Swift 3 (#74). It was also the opportunity to improve a few areas where a breaking change was required.

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 InvalidJSON
• 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, it caches instances between calls, so that the same instance is returned if the method is called twice with the same index name (and before the index is released by the caller).
• 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. (This in theory breaks 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: