.. highlight:: ruby
.. label-release-notes-retina-rest-api
.. _code-examples:
###############################
RELEASE NOTES - Retina REST API
###############################
Update Guide Version 2.2 to 2.3
===============================
Version 2.3 of the **Retina API** sees improvements to the algorithm behind the ``/text`` endpoint.
Fingerprints returned by the ``/text`` endpoint are now generally sparser with a maximum sparsity of 6%
(formerly the maximum sparsity was 12%).
In addition to the ``/text`` endpoint, this change may affect all endpoints which are dependent on the ``/text`` endpoint, such as the following:
* ``/text/keywords``
* ``/text/slicing``
* ``/classify/createCategoryFilter``
And of course, any use of the ``/compare`` or ``/expressions`` endpoints which involve the ``/text`` endpoint.
Note that a Fingerprint created for a document or text using the
older algorithm (v. 2.2), while it will not be exactly the same, will still be very similar to a Fingerprint created for the same document or text using the
newer 2.3 version of the algorithm.
In contrast to the **Retina API**, Fingerprints produced via the **Retina-Spark API** are now more dense (previously these had a maximum sparsity of 2%).
Update Guide Version 2.1 to 2.2
===============================
Main Changes Overview
---------------------
Our API has undergone several improvements and changes. The main changes from version 2.1 are:
* Under the hood
* **NEW** ``/text/detect_language`` endpoint in the Text API tab.
* **NEW** ``/compare/bulk`` endpoint in the Compare API tab.
* **NEW** ``/classify/create_category_filter`` endpoint.
* **NEW** Configurable Swagger user interface
* **NEW** the Retina API is now available on the Microsoft Azure Marketplace.
Changes under the Hood
----------------------
New changes under the hood now result in:
* Speed improvements on all ``text`` related endpoints
* Speed improvements on all ``similar_terms`` endpoints
* Speed improvements on all ``context`` endpoints
NEW ``/text/detect_language`` endpoint
--------------------------------------
There is now a new ``/text/detect_language`` endpoint capable of detecting 50 languages. See our |swagger_api| for more details.
.. |swagger_api| raw:: html
interactive API documentation
NEW ``/compare/bulk`` endpoint
------------------------------
There is now a new ``/compare/bulk`` endpoint, enabling multiple comparisons to be made simultaneously. See our |swagger_api| for more details.
NEW ``/classify/create_category_filter`` endpoint
-------------------------------------------------
We now provide a ``/classify/create_category_filter`` endpoint allowing users to easily create a category filter for a classification system.
For more information see the :ref:`Classification` section and our |swagger_api|.
NEW configurable Swagger UI
---------------------------
Users of Amazon Machine Instance versions of the Retina API can now enable/disable their Swagger user interface as and when required (via the console.sh script's `setup` command).
See the `Amazon Web Services market place `_ and our :ref:`AWS Documentation` for more information on using the Retina API with an Amazon Machine Instance.
NEW Microsoft Azure Marketplace
-------------------------------
The Retina API is now available on Microsoft's Azure Marketplace. More information can be found on our :ref:`Microsoft Azure Marketplace` page.
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 |swagger_api| for full details of all returned objects.
.. |swagger_api| raw:: html
interactive API documentation
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 |swagger_api| for details.