.. _video-methods:

Video Face Detection API Methods
----------------------------------

.. rubric:: In this section:

.. contents::
   :local:

Create Job
^^^^^^^^^^^^^^^^^^^^

.. code::

   POST /job/:id

This method creates a video processing task （job） for the ``findface-video-worker`` component.

.. rubric:: Parameters in path segments

``:id``: job id

.. rubric:: Parameters in request body:

* ``stream_url``: URL/address of a video stream/file to process.
* ``labels``: tag(s) that will be used by the ``findface-facerouter`` component to find processing directives for faces detected in this video stream.
* ``single_pass``: if true, disable restarting video processing upon error (by default, false).
* Other video stream parameters that differ from common video stream parameters specified in the ``findface-video-manager`` configuration file. 

.. rubric:: Returns:

A ``job`` object: all parameters from the request, as well as some read-only attributes.	


.. rubric:: Example

.. rubric:: Request

.. code::

   curl -s 'http://localhost:18810/job/myid-123' --data '{"stream_url":"http://1.2.3.4/stream.mp4", "labels": {"district": "SVAO"}}' | jq

.. rubric:: Response

.. code::

   {
     "id": "myid-123",
     "stream_url": "http://1.2.3.4/stream.mp4",
     "labels": {
       "district": "SVAO"
     },
     "router_url": "http://localhost:1514/",
     "single_pass": false,
     "status": "AWAITING",
     "status_msg": "",
     "statistic": {
       "processed_duration": 0,
       "faces_posted": 0
     },
     "worker_id": ""
   }


List Existing Jobs
^^^^^^^^^^^^^^^^^^^^^^^^

.. code::

   GET /jobs

This method returns the list of all existing jobs.

.. rubric:: Parameters:

This method doesn't accept any parameters.

.. rubric:: Returns:

JSON representation with the list of all jobs.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -s 'http://localhost:18810/jobs' | jq

.. rubric:: Response

.. code::

   [
       {
           "id": "b9c73bhg74hnekpaa0o0",
           "stream_url": "http://1.2.3.4/stream.mp4",
           "labels": {
               "district": "SVAO"
           },
           "router_url": "http://localhost:1514/",
           "single_pass": false,
           "status": "AWAITING",
           "status_msg": "",
           "worker_id": ""
       },
       {
           "id": "b9c73rhg74hnekpaa0og",
           "stream_url": "http://xxx.ru/stream.mp4",
           "labels": {
               "district": "ZAO"
           },
           "router_url": "http://localhost:1514/",
           "single_pass": false,
           "status": "AWAITING",
           "status_msg": "",
           "worker_id": ""
       }
   ]


Retrieve Job Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code::
   
   GET /job/:id

This method retrieves a job parameters by id.

.. rubric:: Parameters in path segments:

``id``: job id.

.. rubric:: Returns:

JSON representation of the job object.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -s 'http://localhost:18810/job/b9c73rhg74hnekpaa0og' | jq

.. rubric:: Response

.. code::

   {
       "id": "b9c73rhg74hnekpaa0og",
       "stream_url": "http://xxx.ru/stream.mp4",
       "labels": {
           "district": "ZAO"
       },
       "router_url": "http://localhost:1514/",
       "single_pass": false,
       "status": "AWAITING",
       "status_msg": "",
       "worker_id": ""
   }


Delete Job
^^^^^^^^^^^^^^^^

.. code::

   DELETE /job/:id

This method deletes a job by id.

.. rubric:: Parameters in path segments:

``id``: job id.

.. rubric:: Returns:

JSON representation of the deleted job object.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -s 'http://localhost:18810/job/myid-123' -X DELETE | jq

.. rubric:: Response

.. code::

   {
     "id": "myid-123",
     "stream_url": "http://1.2.3.4/stream.mp4",
     "labels": {
       "district": "SVAO"
     },
     "router_url": "http://myrouter",
     "single_pass": false,
     "status": "DELETED",
     "status_msg": "",
     "statistic": {
       "processed_duration": 0,
       "faces_posted": 0
     },
     "worker_id": "b9kqns1g74hm6mbmhbqg"
   }

Update Job
^^^^^^^^^^^^^^^

.. code::
 
   PATCH /job/:id

The method updates a job parameters by id.

.. rubric:: Parameters in path segments:

``id``: job id.

.. rubric:: Parameters in request body:

* ``id``: job id.
* ``stream_url``: URL/address of a video stream/file to process.
* ``labels``: tag(s) that will be used by the ``findface-facerouter`` component to find processing directives for faces detected in this video stream.
* ``single_pass``: if true, disable restarting video processing upon error (by default, false).
* ``router_url``: IP address and port of the ``findface-facerouter`` component to receive detected faces from the ``findface-video-worker`` component for processing. 
* ``status``: job status. 
* ``status_msg``: additional job status info.
* ``statistic``: job progress statistics (progress duration, number of posted faces).
* ``worker_id``: id of the ``findface-video-worker`` instance executing the job.
* New values of to-be-modified ``find-video-manager`` configuration parameters. These value have priority over those specified in the ``findface-video-manager`` configuration file.

.. rubric:: Returns:

JSON representation of the updated job object.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -s 'http://localhost:18810/job/myid-123' -X PATCH --data '{"router_url":"http://myrouter"}' | jq

.. code::

   {
     "id": "myid-123",
     "stream_url": "http://1.2.3.4/stream.mp4",
     "labels": {
       "district": "SVAO"
     },
     "router_url": "http://myrouter",
     "single_pass": false,
     "status": "INPROGRESS",
     "status_msg": "",
     "statistic": {
       "processed_duration": 0,
       "faces_posted": 0
     },
     "worker_id": "b9kqns1g74hm6mbmhbqg"
   }


Restart Job
^^^^^^^^^^^^^^^^^^

.. code::

   RESTART /job/:id

This method restarts a job by ID.

.. rubric:: Parameters in path segments:

``id``: job id.

.. rubric:: Returns:

``HTTP/1.1 200 OK`` on success.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -s -D - -X RESTART http://localhost:18810/job/1

.. rubric:: Response

.. code::
 
   HTTP/1.1 200 OK
   Content-Type: application/json
   X-Request-Id: VbhV3vC5
   Date: Tue, 24 Apr 2018 15:23:19 GMT
   Content-Length: 0
   З