Skip to content

Migration guide to version 3.x

Jump to bottom
Clément Le Provost edited this page May 9, 2016 · 4 revisions

Overview

Version 3 brought a few incompatible changes to the Swift client's public interface. This guide will help you adapt your code to work with the new version.

This guide only focuses on incompatible changes. For a complete list of all changes, please refer to ChangeLog.md at the root of the repository.

NOTE: If you are coming from Objective-C, you should read the Objective-C to Swift migration guide first. Although it was created for version 2, it still applies to version 3.

Changes

  • The completion block argument of asynchronous methods has been renamed to completionHandler. If you don't use the trailing closure syntactic sugar, you will have to rename the parameter label everywhere.

  • The Query class has been refactored, leading to parameters being added/renamed/retyped/removed. For a list of all changes, see below.

  • Accessors to obsolete security HTTP headers have been removed (Client.queryParameters, Client.tagFilters, Client.userToken). If you need them:

    1. First please consider migrating to secured API keys, which are now the preferred way to deal with per-user authorization.

    2. If you really need the legacy headers, you may set them via Client.headers.

  • The browse iterator has been moved to a dedicated helper (BrowseIterator). The methods in the Index class are now low-level only.

  • Operations requiring an admin API key have been removed. For obvious security reasons, the admin key should never be used on the client side. There is no plan to reintegrate those features.

Query parameters

Overview

First of all, the Query class now provides low-level methods to access any parameter (even not implemented yet) in an untyped fashion: use the get(name: String)/set(name: String, value: String?) methods or the equivalent subscript operator. You should therefore no longer be blocked by missing parameters.

The class has undergone quite a few changes, with the following goals:

  1. Bring it in line with the REST API. This implies renaming parameters, adding missing parameters or (in some rare cases) removing them.
  2. Achieve 100% Objective-C bridgeability.
  3. Honor the essentially optional nature of all query parameters. (A nil value is acceptable and is the default for all parameters, including primitive types.)
  4. Provide adequate types.

Goals 2 and 3 together lead to some compromises regarding the parameter types: as optional value types (like Int? or enums) are not representable in Objective-C, parameters falling into this category use alternative types:

  • Integers, floats and booleans are typed NSNumber. Since NSNumber is automatically bridged from Int, Double and Bool in Swift, this should be transparent to the user, at least when setting a parameter (less so when reading it).

  • Enums are typed String, because in the end, the underlying value is always a string when calling the API. For convenience, an enum-typed alias is also available (from Swift only) with a trailing underscore.

Detailed changes

Properties have undergone the following changes:

  • aroundLatLong has been renamed aroundLatLng (note the missing O).
  • aroundLatLongViaIP has been renamed aroundLatLngViaIP (note the missing O).
  • facetFilters is now typed [AnyObject]?, using the same JSON notation as the REST API.
  • facetFiltersRaw has been removed. (The equivalent would now be: set("facetFilters", rawValue).)
  • filters is now typed String?.
  • fullTextQuery has been removed. (It was just an alias of query.)
  • ignorePlural has been renamed to ignorePlurals (with a trailing S).
  • insideBoundingBox is now typed [GeoRect]?.
  • insidePolygon is now typed [LatLng]?.
  • minWordSizeForApprox1 has been renamed to minWordSizefor1Typo.
  • minWordSizeForApprox2 has been renamed to minWordSizefor2Typos.
  • numericFilters is now typed [AnyObject]?, using the same JSON notation as the REST API.
  • optionalTagFilters has been removed because it is not part of the public API.
  • optionalWordsMinimumMatched has been removed.
  • queryType is now typed String? (see above), with an enum-typed alias queryType_.
  • removeWordsIfNoResult has been renamed removeWordsIfNoResults. It is now typed String? (see above), with an enum-typed alias removeWordsIfNoResults_.
  • replaceSynonyms has been renamed to replaceSynonymsInHighlight.
  • tagFilters is now typed [AnyObject]?, using the same JSON notation as the REST API.
  • typosOnNumericTokens has been renamed to allowTyposOnNumericTokens.
  • typoTolerance is now typed String? (see above), with an enum-typed alias typoTolerance_.

Some helpers methods have been removed. Use the individual properties instead:

  • addInsidePolygon()
  • resetLocationParameters()
  • searchAroundLatitude()
  • searchAroundLatitudeLongitudeViaIP()
  • searchInsideBoundingBoxWithLatitudeP1()
Clone this wiki locally