.. 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.