Skip to content

Migration guide from 2.x.x to 3.x.x

Jump to bottom
Vincent Voyer edited this page Mar 24, 2015 · 29 revisions

AlgoliaSearch JavaScript client V3 is not backward compatible with V2.

If you have any issue, please contact our team at support@algolia.com.

Table of contents

  1. V2 and V3 examples
  2. Breaking changes
  1. New features
  1. Fixes
  2. Misc

New usage

The V3 release can be summarized in this example:

V2

var client = new AlgoliaSearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function(success, content) {
  // success is true if success or false if error
  // content contains either the results (JS Object) or the error (JS Object)
  console.log(success, content);
});

We changed the way we initialize and do callbacks in V3.

V3

// no more `new AlgoliaSearch(..)` constructor
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function(err, content) {
  // err is null if success or an `Error` object if failure
  // content contains the results or `undefined` if failure
  console.log(err, content);
});

Breaking changes

Now let's see in detail what changed.

new AlogliaSearch(..) => algoliasearch(..)

As we saw it, you must now use algoliasearch('applicationID', 'apiKey'[, opts]) to initialize an API client.

If you call algoliasearch(..) without an applicationID or apiKey, it will throw.

Removed opts

  • opts.dsnHost - Used to specify a particular Distributed Search Network host.
  • use opts.hosts: [dsnHost, host, host] if you really need it
  • opts.dsn - Used to enable/disable DSN on the client. Now done automatically
  • use opts.hosts: [host, host] if you really need it
  • opts.jsonp - Used to force/disable JSONP fallback. The client is now smart enough to automatically do the switch efficiently.

Renamed opts

  • opts.requestTimeoutInMs is now opts.timeout
  • opts.method is now opts.protocol

opts behavior change

  • opts.protocol (in V2 opts.method) must be used as http: or https:
  • opts.hosts
  • If you pass a hosts list to the JavaScript client it will be used without any changes
  • In V2 we cloned and modified the provided hosts list: shuffling and adding a DSN host. This is no more the case

Removed globals

These globals were removed and will throw if you use them:

  • window.AlgoliaSearch
  • window.AlgoliaSearchHelper (see AlgoliaSearchHelper)
  • window.ALGOLIA_VERSION => algoliasearch.version

There's now only one exported global function: algoliasearch, see UMD compatibility to know more.

AlgoliaSearchHelper

The AlgoliaSearchHelper was removed and put into a separate library.

If you were using the AlgoliaSearchHelper, please see the corresponding project for how to use it.

Here's a simple example:

<script src="//cdn.jsdelivr.net/algoliasearch/3.0/algoliasearch.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch.helper/1.0/algoliasearch.helper.min.js"></script>
<script>
var client = algoliasearch('GKDHJFHGN', 'kfhjd02dsfklh');

var helper = algoliasearchHelper( client, 'myMainIndex', { 
  facets : ['mainCharacterFirstName', 'year'],
  disjunctiveFacets : ['producer']
});

helper.addDisjunctiveRefine('director', 'Clint Eastword');
helper.addDisjunctiveRefine('director', 'Sofia Coppola');

helper.addRefine('year', '2003');

helper.search('', function(err, content) {
  console.log(err, content);
});
</script>

Callback convention

All asynchronous methods are now using these two conventions:

You can also use promises

Changed function signatures

Due to the change in the callback convention, we modified these functions:

  • index.search
    • V2: index.search(query[, callback|params, delay])
    • V3:
      • index.search(query[, cb])
      • index.search(query[, params, cb])
      • index.search(params[, cb]) where params.query is filled
      • We removed the delay param. Delaying can be done on your side using lodash.debounce
      • index.search is an important function, we made it so it can be used in multiple ways
  • client.getLogs
    • V2: client.getLogs(cb[, offset, length])
    • V3: client.getLogs([offset, length, cb])
  • client.listIndexes
    • V2: client.listIndexes(cb[, page])
    • V3: client.listIndexes([page, cb])
  • client|index.addUserKeyWithValidity
    • V2: client|index.addUserKeyWithValidity(acls, validity, maxQueriesPerIPPerHour, maxHitsPerQuery, cb)
    • V3: client|index.addUserKeyWithValidity(acls, {validity, maxQueriesPerIPPerHour, maxHitsPerQuery}[, cb])
  • client.sendQueriesBatch
    • V2: client.sendQueriesBatch(cb, delay)
    • V3: client.sendQueriesBatch([cb])
    • We removed the delay parameter. Delaying can be done on your side using lodash.debounce.
  • index.addObject
    • V2: index.addObject(content[, callback, objectID])
    • V3: index.addObject(content[, objectID, callback])
  • index.getObject
    • V2: index.getObject(objectID[, callback, attributes])
    • V3: index.getObject(objectID[, attrs, callback])
  • index.browse
    • V2: index.browse(page, cb[, hitsPerPage])
    • V3: index.browse(page[, hitsPerPage, cb])

Removed JSON2.js

In ᵛ² we were previously including JSON2.js as part of our build.

This was done to support browsers like IE7.

If you still need to support browsers not providing JSON.* functions.

Use this:

<!--[if lte IE 7]>
<script src="//cdnjs.cloudflare.com/ajax/libs/json2/20140204/json2.min.js"></script>
<![endif]-->

New features

UMD compatibility

We now support all major module loaders.

So that you can use our client with:

If you are not using any module loader, no problem it will export the algoliasearch property on the window object.

Browserify

Being CommonJS compatible means that you can now:

npm install algoliasearch --save
var algoliasearch = require('algoliasearch');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function(err, content) {
  console.log(err, content);
});

Promises

The JavaScript client now supports both promises and callbacks for asynchronous calls.

var algoliasearch = require('algoliasearch');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');

index.search('something')
  .then(function success(content) {
    console.log('Success', content);
  })
  .catch(function failure(err) {
    console.log('Failure', err);
  });

The promise implementation is the native Promise from the browser or jakearchibald/es6-promise for browsers not supporting the Promise object.

When using the jQuery build, you will get a jQuery promise.

When using the AngularJS build, you will get an AngularJS promise.

callback AND promise?

No.

If you pass a callback, you won't get a promise. If no callback passed, you get a promise.

Fixes

  • IE10 now uses XHR instead of XDR
  • Do not retry when server sends 4xx or 1xx
  • Distinguish jQuery timeout from error
  • Distinguish AngularJS timeout from error
  • Retry with JSONP when AngularJS or jQuery error on request

Misc

The JavaScript client is now fully tested in many browsers.

Our builds are done with browserify.

Clone this wiki locally