API
===================

.. _api:

FindFace Lite API is located on :code:`http://<your_hostname>/api-docs`. It is interactive, which means that you can make requests and get responses right on this page.

API documentation allows to read, create, update and delete all entities and provides description for all methods and parameters.

In this article we will overview the blocks of FindFace Lite functionality accessible via API and how to use interactive API.


Preparation to API usage
------------------------

Before use the FindFace Lite API, please, authentificate yourself by creating JWT token in the **AUTHENTICATION** section.

Enter **username** and **password** from the :ref:`STEP 5 <step5>` of **Getting started** block into the form and click the **SET TOKEN** button. 

 .. image:: /images/authentification.png
   :scale: 40%

After authentification you can use interactive FindFace Lite API. 

.. note:: 
    
    If you need to use API requests outside the interactive API, please, use the created token. 


API usage overview
-------------------

API page is divided into 2 parts: left is a list of operations and right are operations execution field.

 .. image:: /images/api.png
  :scale: 20%

Each operaton consists of **Request** and **Response** part:

* Request part describes the operation, including **request schema** with the interpretation of each parameter, **request example** and **TRY** button, which sends the request.

 .. image:: /images/request.png
  :scale: 30%

* Response part describes the **schema** and **examples** of each variant of response on the given operation.

 .. image:: /images/response_ex.png
  :scale: 30%

After the **TRY** button is clicked, request is sent and you will see the response block with the **response status** and detailed information.

 .. image:: /images/response_status.png
    :scale: 40%


FindFace Lite API functionality 
--------------------------------

API documentation can be divided into the semantic blocks, which contain all requests (to get, add, edit and delete entities):

1. **Recognition flow**

    * **Camera** block manages Camera object, which is a representation of any video stream (it also can be a file). Active Camera receives detection data from :term:`VideoWorker` and converts it to Events. 

    * **Event** block manages Event object, which is a representation of an object (face or car) occurrence in the camera frame. With active Camera Event is automaticaly created from VideoWorker detection data. You or any 3rd party system can also create it outside the main flow using POST request.

    * **Card** block manages Card object, which is a profile of a real person or a car. Card can be one of two types: *face* or *car*.

    * **Object** block manages Object, which is a representation or particular face or car. To create it, you have to add the image and link it to the Card. 
 
    |flow_full|

   .. |flow_full| image:: /images/flow_full.png
      :scale: 70%

   .. |flow_full_ru| image:: /images/flow_full_ru.png
      :scale: 70%

2. **External system intereaction**

    * **Webhook** block can be used to notify external systems about Events and matches.

3. **Authentification and user management**

    * **Auth** block describes methods used for authentication.

    * **User** block manages Findface Lite users 

4. **System operations**

    * **Misc** block contains undefined requests, connected with the service needs. 
    
    * **Pipeline** block is an internal method for :term:`VideoWorker` and normally is not used in usual flow.