Skip to content

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

Jump to bottom
Sylvain Utard edited this page Mar 27, 2015 · 29 revisions

AlgoliaSearch JavaScript client V3 is not backward compatible with V2.

If you have any issue, please contact our team at [email protected].

Table of contents

  1. V2 and V3 examples
  2. Breaking changes
  1. New features
  1. Fixes
  2. Misc
  3. Can I still use V2?

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);
}, { hitsPerPage: 42 });

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', { hitsPerPage: 42 }, 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/algoliasearch.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch.helper/1/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.

Can I still use V2?

Yes. If you are using the V2 of our JavaScript client and do not want to upgrade then you can stick to V2.

We have a V2 branch where we will publish critical updates. They will then be pushed to jsDelivr.

Clone this wiki locally