``sf-api``
---------------------------------

The ``sf-api`` service implements the HTTP API for the main functionality of the FindFace Server such as object detection and object recognition.

.. note::
   The mentioned functions themselves are provided by ``extraction-api``.

The ``sf-api`` interfaces with the following FindFace Server components:

* feature vector database powered by Tarantool via the ``tntapi`` service
* ``extraction-api`` that provides object detection and object recognition
* ``upload`` that provides a storage for original images and FindFace Server artifacts

To detect an object in an image, you need to send the image as a file or URL in an :ref:`API request <biometric-api>` to ``sf-api``. The ``sf-api`` will then redirect the request to ``extraction-api`` for object detection and recognition.

If there is a configured video object detection module in the system, ``sf-api`` also interfaces with the router service (e.g. ``facerouter``). It receives data of detected objects and processing directives from the router service (``facerouter``) and executes the received directives (for example, saves objects into a specific database gallery).

.. tip::
   You can also :ref:`directly <extraction_api>` access ``extraction-api``.

Functionality:

* :ref:`HTTP API <biometric-api>` implementation (object detection and object recognition methods, performed via ``extraction-api``).
* saving object data to the feature vector database (performed via ``tntapi``),
* saving original images, object thumbnails and normalized object images to an NginX-powered web server (via ``upload``).
* provides interaction between all the FindFace Server components.

The ``sf-api`` configuration is done through environment variables and command line flags or through the ``sf-api.yaml`` configuration file. You can find its default content :download:`here <_scripts/default_sf-api.yaml>`.

When configuring ``sf-api``, refer to the following parameters:


.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Command line flags
       - Type
       - Description
     * - ``-cache``
       - string
       - Cache type: inmemory, redis or memcache (default ``memcache``).
     * - ``-cache-inmemory-size``
       - int
       - Maximum number of items in ARC cache (default 16384).
     * - ``-cache-memcache-dns-cache-timeout``
       - duration
       - DNS cache timeout (default 1m0s).
     * - ``-cache-memcache-nodes``
       - value
       - Comma-separated list of memcache shards (default ``127.0.0.1:11211``).
     * - ``-cache-memcache-timeout``
       - duration
       - Specifies read/write timeout (default 100ms).
     * - ``-cache-redis-db``
       - int
       - Database to be selected after connecting to the server.
     * - ``-cache-redis-network``
       - string
       - Network type, either tcp or unix (default ``tcp``).
     * - ``-cache-redis-nodes``
       - value
       - Array of Host:Port addresses (default ``localhost:6379``).
     * - ``-cache-redis-password``
       - string
       - Optional password. Must match the password specified in the requirepass server configuration option.
     * - ``-cache-redis-timeout``
       - duration
       - Specifies dial/read/write timeout (default 5s).
     * - ``-config``
       - string
       - Path to config file.
     * - ``-config-template``
       -
       - Output config template and exit.
     * - ``-debug``
       - –
       - Enable debug logging.
     * - ``-extraction-api-extraction-api``
       - string
       - Extraction API address legacy argument – please switch to '`url`'.
     * - ``-extraction-api-keepalive``
       - duration
       - Keep-alive connection timeout (default 24h0m0s).
     * - ``-extraction-api-max-idle-conns-per-host``
       - int
       - Max idle keep-alive connections per host (default 20).
     * - ``-extraction-api-timeouts-connect``
       - duration
       - extraction-api-timeouts-connect (default 5s).
     * - ``-extraction-api-timeouts-idle-connection``
       - duration
       - extraction-api-timeouts-idle-connection (default 10s).
     * - ``-extraction-api-timeouts-overall``
       - duration
       - extraction-api-timeouts-overall (default 35s).
     * - ``-extraction-api-timeouts-response-header``
       - duration
       - extraction-api-timeouts-response-header (default 30s).
     * - ``-extraction-api-trace``
       - –
       - Enable HTTP tracing (extremely verbose, slows everything down considerably).
     * - ``-extraction-api-url``
       - string
       - Extraction API address (default ``http://127.0.0.1:18666``).
     * - ``-generate-openapi``
       - –
       - Flag for generating openapi docs and exit.
     * - ``-help``
       - –
       - Print help information.
     * - ``-limits-allow-return-facen``
       - –
       - Allow returning raw feature vectors to detect responses if ``?return_facen=true`` (v2) or ``?return_emben=true`` (v3).
     * - ``-limits-body-image-length``
       - int
       - Maximum length of image supplied in request body (default 33554432).
     * - ``-limits-deny-networks``
       - string
       - Comma-separated list of subnets that are not allowed to fetch from (default ``127.0.0.0/8,192.168.0.0/16,10.0.0.0/8,::1/128,fe00::/8``).
     * - ``-limits-url-length``
       - int
       - Maximum supported url length in bytes (default 4096).
     * - ``-listen``
       - string
       - IP:port to listen on (default ``:18411``).
     * - ``-normalized-storage-enabled``
       - –
       - Enables normalize saving (default true).
     * - ``-normalized-storage-s3-access-key``
       - string
       -  Access key for the object storage.
     * - ``-normalized-storage-s3-bucket-name``
       - string
       - S3 storage bucket name.
     * - ``-normalized-storage-s3-endpoint``
       - string
       - S3 compatible object storage endpoint.
     * - ``-normalized-storage-s3-operation-timeout``
       - int
       -  Storage operations (Get, Put, Delete) timeout in seconds (default 30).
     * - ``-normalized-storage-s3-public-url``
       - string
       - Storage public URL.
     * - ``-normalized-storage-s3-region``
       - string
       - Storage region.
     * - ``-normalized-storage-s3-secret-access-key``
       - string
       - Secret key for the object storage.
     * - ``-normalized-storage-s3-secure``
       - –
       - If ``true`` API requests will be secure (HTTPS), and insecure (HTTP) otherwise (default true).
     * - ``-normalized-storage-webdav-keepalive``
       - duration
       - Keep-alive connection timeout (default 24h0m0s).
     * - ``-normalized-storage-webdav-max-idle-conns-per-host``
       - int
       - Max idle keep-alive connections per host (default 20).
     * - ``-normalized-storage-webdav-timeouts-connect``
       - duration
       - normalized-storage-webdav-timeouts-connect (default 5s).
     * - ``-normalized-storage-webdav-timeouts-idle-connection``
       - duration
       -  normalized-storage-webdav-timeouts-idle-connection (default 10s).
     * - ``-normalized-storage-webdav-timeouts-overall``
       - duration
       - normalized-storage-webdav-timeouts-overall (default 35s).
     * - ``-normalized-storage-webdav-timeouts-response-header``
       - duration
       - normalized-storage-webdav-timeouts-response-header (default 30s).
     * - ``-normalized-storage-webdav-trace``
       - –
       - Enable HTTP tracing (extremely verbose, slows everything down considerably).
     * - ``-normalized-storage-webdav-upload-url``
       - string
       - Webdav storage for normalized, disable normalized if empty string (default ``http://127.0.0.1:3333/uploads/``).
     * - ``-normalized_storage``
       - string
       - Normalized storage type: webdav, s3 (default ``webdav``).
     * - ``-objects``
       - value
       - Supported object types (default face,body,car).
     * - ``-storage-api-cooldown``
       - duration
       - Cooldown timeout after communication error (default 2s).
     * - ``-storage-api-galleries-read-slave-first``
       -
       - Prefer slaves over master for get/list galleries requests.
     * - ``-storage-api-keepalive``
       - duration
       - Keep-alive connection timeout (default 24h0m0s).
     * - ``-storage-api-max-idle-conns-per-host``
       - int
       - Max idle keep-alive connections per host (default 20).
     * - ``-storage-api-max-slave-attempts``
       - int
       - Give up after trying to read from max_slave_attempts slaves (default 2).
     * - ``-storage-api-read-slave-first``
       - –
       - Prefer slaves over master for requests.
     * - ``-storage-api-read-slave-only``
       - –
       - Ignore master on read requests. If true: ReadSlaveFirst will be ignored.
     * - ``-storage-api-timeouts-connect``
       - duration
       - storage-api-timeouts-connect (default 5s).
     * - ``-storage-api-timeouts-idle-connection``
       - duration
       - storage-api-timeouts-idle-connection (default 10s).
     * - ``-storage-api-timeouts-overall``
       - duration
       - storage-api-timeouts-overall (default 35s).
     * - ``-storage-api-timeouts-response-header``
       - duration
       - storage-api-timeouts-response-header (default 30s).
     * - ``-storage-api-trace``
       - –
       - Enable HTTP tracing (extremely verbose, slows everything down considerably).

The format of environment variable for flag ``-my-flag`` is ``CFG_MY_FLAG``.

Priority:

#. Defaults from source code (lowest priority).
#. Config file.
#. Environment variables.
#. Command line.