Update Guide Version 1.x to 2.x

Main Changes Overview

Our API has undergone several improvements and changes. The main changes from version 1 are:

  • Under the hood
  • Changes to the Swagger UI interactive API
  • Changes to api-key usage
  • Returned objects have changed
  • Some endpoints no longer exist
  • Some parameters no longer exist
  • Changes to parameter and endpoint naming
  • NEW Fingerprint option
  • NEW bulk operation endpoints
  • NEW image endpoints (including bulk)

Under the Hood

The relevant changes under the hood are:

  • Faster and more accurate keyword endpoint
  • Faster and more accurate text to fingerprint transformation
  • Generally faster REST backend

Changes to Swagger UI interactive API

If you’re using our interactive API you will immediately see that the user interface has changed to an overview page with a menu bar. Each menu item on the menu bar displays the endpoints for a particular (sub) api in a frame below the menu bar.

Changes to API key usage

Up to Version 2.2.0 Due to security reasons, the mode of supplying your api-key has changed. You can still use the same api-key that was issued to you. The key now has to be supplied as a HTTP-Header with the new name api-key. (Beware: this new name uses a dash - whereas the former name of the parameter api_key used an underscore character ). It is no longer possible to supply the key as a Query parameter.

Returned objects have changed

The objects returned by our API now have a modified structure. For instance, the Term object now has the form:

Term {
  fingerprint (Fingerprint, optional): The Fingerprint of this term.,
  df (number, optional): The df value of this term.,
  term (string, optional): The term as a string.,
  pos_types (array[string], optional): The pos types of the term.,
  score (number, optional): The score of this term.
}

Please see the individual endpoints of our interactive API documentation for full details of all returned objects.

Some Endpoints no longer exist

The specialized API endpoints for operations on Fingerprints no longer exist. Please note that Fingerprints can be obtained by setting the get_fingerprint parameter on the relevant endpoints.

Some Parameters no longer exist

The returnType parameter no longer exists. Users requiring an Image return type should now use the new Image API.

The plotShape parameter has been removed from all Text, Term, Compare and Expressions endpoints (because these endpoints no longer return images).

The imageScalar parameter has been removed from the Compare API (because this endpoint no longer returns images).

Changes to parameter and endpoint naming

Please be aware that names of endpoints and parameters have changed from camelCase to snake_case.

In particular, the /terms/similarTerms and /expressions/similarTerms endpoints are now /terms/similar_terms and /expressions/similar_terms respectively.

NEW Fingerprint option

You will notice that many endpoints now have a get_fingerprint parameter. Unless you specifically need a Fingerprint in the response object we recommend that you set this to the default value of false .

NEW Image API

A new Image API has been added, collecting all image endpoints in one place for ease of use.

NEW bulk operation endpoints

In order to minimise network overhead for users, new bulk operation endpoints have been added to the following APIs:

  • Text API
  • Expressions API
  • Image API

Please see the relevant interactive API documentation for details.