.. _tarantool-api:

Direct API Requests to Tarantool
======================================

You can use HTTP API to extract object data (faces, bodies, cars) directly from the Tarantool Database. 

.. note::
   In the current implementation, Tarantool operates objects as faces. For example, to add an object, send ``POST /:ver/faces/add/:name``.

.. rubric:: In this section:

.. contents::
   :local:


General Information
----------------------------

API requests to Tarantool are to be sent to ``http://<tarantool_host_ip:port>``.

.. tip:: 
    The port for API requests can be found in the ``FindFace.start`` section of the Tarantool configuration file ``/etc/tarantool/instances.available/*.lua``:

    .. code::

       cat /etc/tarantool/instances.available/*.lua

       ##8101:
       FindFace.start("127.0.0.1", 8101)

.. note::
    In the case of the standalone deployment, you can access Tarantool by default only locally (127.0.0.1). If you want to access Tarantool remotely, :ref:`alter <tarantool-server-config>` the Tarantool configuration file (``/etc/tarantool/instances.available/*.lua``).


API requests to Tarantool may contain the following parameters in path segments:


* ``:ver``: API version (v2 at the moment).
* ``:name``: gallery name.

By default, there are the following galleries in the Tarantool database:

* ``ffsec_body_events``: feature vectors extracted from bodies detected in the video.
* ``ffsec_body_objects``: feature vectors extracted from bodies in dossier photos.
* ``ffsec_car_events``: feature vectors extracted from cars detected in the video.
* ``ffsec_car_objects``: feature vectors extracted from cars in dossier photos.
* ``ffsec_face_events``: feature vectors extracted from faces detected in the video.
* ``ffsec_face_objects``: feature vectors extracted from faces in dossier photos.
* ``ffsec_user_face``: feature vectors extracted from the FindFace Multi users' photos, used for face-based authentication.
* ``ffsec_persons``: centroids of persons (virtual feature vectors averaged across all person's faces) and metadata.

.. tip::
   To list gallery names on a shard, type in the following command in the address bar of your browser: 

   .. code::

      http://<tarantool_host_ip:shard_port>/stat/list/1/99

   The same command on the console is as such:

   .. code::

      curl <tarantool_host_ip:shard_port>/stat/list/1/99 \| jq

   You can also list gallery names by using a direct request to Tarantool:

   .. code::

      echo 'box.space.galleries:select()' | tarantoolctl connect <tarantool_host_ip:shard_port>

   Note that if there is a large number of shards in the system, chances are that a randomly taken shard does not contain all the existing galleries. In this case, just list galleries on several shards.



Add Object
----------------------


.. code::

   POST /:ver/faces/add/:name

.. rubric:: Parameters in body:

JSON-encoded array of objects with the following fields:
  
* ``"id"``: object id in the gallery, uint64_t,
* ``"facen"``: raw feature vector, base64,
* ``"meta"``: object metadata, dictionary.


.. rubric:: Returns:

*  HTTP 200 and empty body on success.
*  HTTP 404 if a gallery with the given name doesn't exist.
*  HTTP with a status other than 200 and error description in the body on failure.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D - -s 'http://localhost:8101/v2/faces/add/testgal' --data '
   [
     {
       "id": 9223372036854776000,
       "facen": "qgI3vZRv/z…NpO9MdHavW1WuT0=",
       "meta": {
   "cam_id": "223900",
   "person_name": "Mary Ostin",

       }
     }
   ]

.. rubric:: Response

.. code::

   HTTP/1.1 200 Ok
   Content-length: 1234
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive


Remove Object
--------------------

.. code::

   POST /v2/faces/delete/:name

.. rubric:: Parameters in body:

JSON-encoded array of object ids to be removed

.. rubric:: Returns:

* HTTP 200 and empty body on success.
* HTTP 404 if an object with the given id is not found in the gallery. 
* HTTP with a status other than 200 and error description in the body on failure.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D -  -s 'http://localhost:8101/v2/faces/delete/testgal' --data '[1, 4, 922, 3]'

.. rubric:: Response

.. code::

   HTTP/1.1 200 Ok
   Content-length: 111
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive


Object Search
-------------------

.. code::

   POST /v2/faces/search/:name

.. rubric:: Parameters in body:

JSON-encoded search request with the following fields:

* ``limit``: maximum number of objects in the response. 
* ``sort``: sorting order. Pass one of the following values: ``id``: increasing order by id, ``-id``: decreasing order by id, ``-score``: decreasing order by object similarity (only if you search for objects with similar feature vectors). 
* ``filter`` (filters):

   * ``facen``: (optional) search for objects with similar feature vectors. Pass a dictionary with the following fields: ``data``: raw feature vector, base64; ``score``: range of similarity between objects [threshold similarity; 1], where ``1`` is 100% match.
   * ``id`` and ``meta/<meta_key>``: search by object id and metastring content. To set this filter, use the following operators:

     * ``range``: range of values, only for numbers.
     * ``set``: id or metastring must contain at least one value from a given set, for numbers and strings.
     * ``subset``: id or metastring must include all values from a given subset, for numbers and strings.
     * ``like``: by analogy with ``like`` in SQL requests: only 'aa%', '%aa', and '%aa%' are supported. Only for strings and set[string]. In the case of set[string], the filter will return result if at least one value meets the filter condition.
     * ``ilike``: by analogy with ``like`` but case-insensitive, only for strings and set[string].


.. rubric:: Returns:

* JSON-encoded array with objects on success. The value in the ``X-search-stat`` header indicates whether the fast index was used for the search: ``with_index`` or ``without_index``.

  .. note::
     Fast index is not used in API v2.

* HTTP with a status other than 200 and error description in the body on failure.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D - -s 'http://localhost:8101/v2/testgal/search' --data '
   {
   	   "limit": 2,
       "sort": {
	   	   "score": -1
	   },
	   "filter": {
		   "facen": {
			   "data": "qgI3vZRv/z0BQTk9rcirOyZrNpO9MdHavW1WuT0=",
			   "score": [0.75, 1]
		   },
		   "id": {
			   "range": [9223372036854000000, 9223372036854999000]
		   },
		   "meta": {
			   "person_id": {
				   "range": [444, 999]
			   },
			   "cam_id": {
				   "set": ["12767", "8632", "23989"]
			   }
		   }
	   }
   }'


.. rubric:: Response

.. code::

   HTTP/1.1 200 Ok
   Content-length: 1234
   X-search-stat: without_index
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive

   {
     "results": [
       {
         "facen": " qgI3vZRv/z0BQTk9rcirOyZrNpO9MdHavW1WuT0=",
         "meta": {
           "timestamp": 0,
           "photo_hash": "",
           "person_id": 777,
           "cam_id": "8632"
         },
         "score": 0.9964,
         "id": 9223372036854776000
       }
     ]
   }





Edit Object Metadata and Feature Vector
-------------------------------------------

.. code::

   POST /v2/faces/update/:name

.. rubric:: Parameters in body:

JSON-encoded array with objects with the following fields:

* ``"id"``: object id, uint64_t.
* ``"facen"``: (optional) new feature vector, base64. If omitted or passed as ``null``, the relevant field in the database won't be updated.
* ``"meta"``: dictionary with metadata to be updated. If some metastring is omitted or passed as ``null``, the relevant field in the database won't be updated.

.. rubric:: Returns:

* HTTP 200 and dictionary with all object parameters, including not updated, on success.
* HTTP 404 and error description if an object with the given id doesn't exist.
* HTTP with a status other than 200 and error description in the body on failure.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D - -s 'http://localhost:8101/v2/faces/update/sandbox' --data '[{"id":1,"facen":null,"meta":{"m:timestamp":1848}}]'

.. rubric:: Response

.. code::

   HTTP/1.1 200 Ok
   Content-length: 151
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive

   {"meta":{"m:timestamp":1848,"normalized_id":"1_b9pkrf00mjt6h1vmq1kg.png","m:cam_id":"a9f7a973-f07e-469d-a3bd-41ddd510b26f","feat":"{\"score\":0.123}"}, "id":1, ... }




List Galleries
-----------------------

.. code::

   POST /v2/galleries/list

.. rubric:: Returns:

JSON-encoded array with galleries with the following fields: ``name``: gallery name, ``faces``: number of objects in a gallery.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D - -s -X POST http://localhost:8101/v2/galleries/list

.. rubric:: Response

.. code::

   HTTP/1.1 200 Ok
   Content-length: 42
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive

   {
     "results": [
       {
         "name": "testgal",
         "faces": 2
       }
     ]
   }

Get Gallery Info
------------------------

.. code:: 

   POST /v2/galleries/get/:name

.. rubric:: Returns:

* HTTP 200 and dictionary with gallery parameters on success.
* HTTP 404 and error description if a gallery with the given name doesn't exist.
* HTTP with a status other than 200 and error description in the body on failure.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D - -s -X POST http://localhost:8101/v2/galleries/get/testgal

.. code::

   HTTP/1.1 200 Ok
   Content-length: 11
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive

   {"faces":2}

Create Gallery
---------------------

.. code::

   POST /v2/galleries/add/:name


.. rubric:: Returns:

* HTTP 200 and empty body on success.
* with a status other than 200 and error description in the body on failure.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D - -X POST -s 'http://localhost:8101/v2/galleries/add/123'

.. rubric:: Response

.. code::

   HTTP/1.1 409 Conflict
   Content-length: 57
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive

   {"error":{"message":"gallery already exists","code":409}}

Remove Gallery
----------------------

.. code::

   POST /v2/galleries/delete/:name

.. rubric:: Returns:

* HTTP 200 and empty on success.
* with a status other than 200 and error description in the body on failure.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -D - -X POST -s 'http://localhost:8101/v2/galleries/delete/123'

.. rubric:: Response

.. code::

   HTTP/1.1 204 No content
   Content-length: 0
   Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc)
   Connection: keep-alive