.. _api-test:

Test Requests
-----------------------

Before you can proceed with development to implement the face recognition services to your system, make sure that the FindFace Server components are working. To do so, run the test requests below, minding the sequence. To pretty-print responses, we recommend you to use :program:`jq`.

.. rubric:: In this section:

.. contents::
   :local:


How to Pretty-Print Responses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use :program:`jq` to parse JSON data in responses. The :program:`jq` tool is automatically installed from the console installer. 

.. tip::
   If it is not so, install :program:`jq` as such::

     sudo apt install jq

.. note::
   Since :program:`jq` approximates integers larger than 2^53 (e.g., for ``"id":12107867323949968228``, the output is ``"id": 12107867323949967000``, etc.), you may want to use :program:`json_pp` instead.

  

Create Gallery
^^^^^^^^^^^^^^^^^^^^^^

The following request creates a new gallery ``galleryname``. Relevant HTTP API method: ``/galleries/<gallery> POST``.

.. rubric:: Request

::

 curl -s -X POST http://localhost:18411/v2/galleries/galleryname | jq

.. rubric:: Response

::

 {}

List Galleries
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following request returns the names of existing galleries (``galleryname``). Relevant HTTP API method: ``/galleries GET``.

.. rubric:: Request

::

 curl -s http://localhost:18411/v2/galleries | jq

.. rubric:: Response

::

 {
   "galleries": [
     {
       "name": "galleryname",
       "faces": 0
     }
   ]
 }


Detect Face in Image
^^^^^^^^^^^^^^^^^^^^^^^^^^

The 1st request detects a face in a sample Internet image and returns coordinates of the rectangle around the face (a.k.a. bbox) and the face orientation. Relevant HTTP API method: ``/detect POST``.

.. rubric:: Request #1

::

 curl -s -H 'Content-Type: text/x-url' -d https://static.findface.pro/sample.jpg -X POST http://localhost:18411/v2/detect | jq

.. rubric:: Response

::

 {
   "faces": [
     {
       "bbox": {
         "left": 595,
         "top": 127,
         "right": 812,
         "bottom": 344
       },
       "features": {
         "score": 0.9999999
       }
     }
   ],
   "orientation": 1
 }

If ``facen=on``, the detection result is saved in ``memcached``. In the 2nd request, the image is the same but this time ``facen=on``, along with enabled gender, age and emotions recognition. 

.. tip::
   To retrieve the detection result from ``memcached``, use the ``/detect GET`` method.

.. rubric:: Request #2

::

 curl -s -H 'Content-Type: text/x-url' -d https://static.findface.pro/sample.jpg -X POST 'http://localhost:18411/v2/detect?facen=on&gender=on&age=on&emotions=on' | jq

.. rubric:: Response

::

 {
   "faces": [
     {
       "id": "bhse5elubdg0ajgm2nkg",
       "bbox": {
         "left": 595,
         "top": 127,
         "right": 812,
         "bottom": 344
       },
        "features": {
         "gender": {
           "gender": "FEMALE",
           "score": -2.6415923
         },
         "age": 26.04833,
         "score": 0.9999999,
         "emotions": [
           {
             "emotion": "neutral",
             "score": 0.99958
           },
           {
             "emotion": "sad",
             "score": 0.0004020398
           },
           {
             "emotion": "happy",
             "score": 8.603504e-06
           },
           {
             "emotion": "surprise",
             "score": 8.076798e-06
           },
           {
             "emotion": "disgust",
             "score": 6.653509e-07
           },
           {
             "emotion": "angry",
             "score": 6.14346e-07
           },
           {
             "emotion": "fear",
             "score": 7.33713e-10
           }
         ]
       }
     }
   ],
   "orientation": 1
 }


The 3rd request detects a face in another image and is used merely for the purpose of database population. The detection result is saved in ``memcached`` (``facen=on``). 

.. rubric:: Request #3

::

 curl -s -H 'Content-Type: text/x-url' -d https://static.findface.pro/sample2.jpg -X POST 'http://localhost:18411/v2/detect?facen=on

.. rubric: Response

::

 {
   "faces": [
     {
       "id": "bhse45dubdg0ajgm2nk0",
       "bbox": {
         "left": 515,
         "top": 121,
         "right": 821,
         "bottom": 427
       },
       "features": {
         "score": 0.9999982
       }
     }
   ],
   "orientation": 1
 }



Retrieve Detection Result from ``memcached``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following request retrieves the detection result from ``memcached`` by id. Related HTTP API method: ``/detect GET``.

.. note::
   ``bhse5elubdg0ajgm2nkg`` is the id of the detection results in memcached. This id is provided only for reference. To create valid requests out of the example, replace the identifier with those actually received in the previous responses. 

.. important::
   Before you proceed, open the ``findface-sf-api`` configuration file and make sure that the ``allow-return-facen`` parameter is ``on``. 

   .. code::

      sudo vi /etc/findface-sf-api.ini

      allow-return-facen: on



.. rubric:: Request #1

::

 curl -s 'http://localhost:18411/v2/detect/bhse5elubdg0ajgm2nkg' 

.. rubric:: Response

::

 {
   "id": "bhse5elubdg0ajgm2nkg",
   "bbox": {
     "left": 595,
     "top": 127,
     "right": 812,
     "bottom": 344
   },
   "features": {
     "score": 0.9999999
   }
 }

To retrieve a face feature vector (facen) in a detection result, open the ``/etc/findface-sf-api.ini`` configuration file and set ``allow-return-facen: true``. Restart ``findface-sf-api`` and append the ``return_facen=on`` query string parameter to the previous command:

.. rubric:: Request #2

::

 curl -s 'http://localhost:18411/v2/detect/bhse5elubdg0ajgm2nkg?return_facen=on' | jq       

.. rubric:: Response

::

 {
   "id": "bhse5elubdg0ajgm2nkg",
   "bbox": {
     "left": 595,
     "top": 127,
     "right": 812,
     "bottom": 344
   },
   "features": {
     "score": 0.9999999
   },
   "facen": "1ji...Vr3TEQg8"
 }

 

Add Face from ``memcached`` to Gallery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following requests not only retrieve the detection results from ``memcached`` by their id's but also add the results to the gallery ``galleryname`` under different custom ids (to be specified in a request). Relevant HTTP API method: ``/v2/galleries/<gal>/faces/<id>``.

.. rubric:: Request #1

::

 curl -s -X POST -H 'Content-Type: application/json' --data '{"from":"detection:bd2blott8f63g8nbhi50"}' http://localhost:18411/v2/galleries/galleryname/faces/1 | jq

.. rubric:: Response

::

 {
   "id": {
     "gallery": "galleryname",
     "face": 1
   },
   "features": {
     "gender": {
       "gender": "FEMALE",
       "score": -2.6415923
     },
     "age": 26.04833,
     "score": 0.9999999,
     "emotions": [
       {
         "emotion": "neutral",
         "score": 0.99958
       },
       {
         "emotion": "sad",
         "score": 0.0004020398
       },
       {
         "emotion": "happy",
         "score": 8.603504e-06
       },
       {
         "emotion": "surprise",
         "score": 8.076798e-06
       },
       {
         "emotion": "disgust",
         "score": 6.653509e-07
       },
       {
         "emotion": "angry",
         "score": 6.14346e-07
       },
       {
         "emotion": "fear",
         "score": 7.33713e-10
       }
     ]
   },
   "meta": {},
   "normalized_id": "3_bd323i5t8f66ph0eafq0.png"
 }

.. rubric:: Request #2

::

 curl -s -X POST -H 'Content-Type: application/json' --data '{"from":"detection: bd44p6dt8f66ph0eahkg "}' http://localhost:18411/v2/galleries/galleryname/faces/2 | jq


List Gallery Faces
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following request returns the list of faces in the gallery ``galleryname``. Relevant HTTP API method: ``/galleries/<gallery>/faces`` with the active ``limit=`` filter (maximum number of returned faces).

.. rubric:: Request

::

 curl -s 'http://localhost:18411/v2/galleries/galleryname/faces?limit=2' | jq

.. rubric: Response

::

 {
   "faces": [
     {
       "id": {
         "gallery": "galleryname",
         "face": 1
       },
       "features": {
         "gender": {
           "gender": "FEMALE",
           "score": -2.6415923
         },
         "age": 26.04833,
         "score": 0.9999999,
         "emotions": [
           {
             "emotion": "neutral",
             "score": 0.99958
           },
           {
             "emotion": "sad",
             "score": 0.0004020398
           },
           {
             "emotion": "happy",
             "score": 8.603504e-06
           },
           {
             "emotion": "surprise",
             "score": 8.076798e-06
           },
           {
             "emotion": "disgust",
             "score": 6.653509e-07
           },
           {
             "emotion": "angry",
             "score": 6.14346e-07
           },
           {
             "emotion": "fear",
             "score": 7.33713e-10
           }
         ]
       },
       "meta": {},
       "normalized_id": "1_bd321tlt8f66ph0eaflg.png"
     },
     {
       "id": {
         "gallery": "galleryname",
         "face": 2
       },
       "features": {
         "gender": {
           "gender": "FEMALE",
           "score": -2.6415923
         },
         "age": 26.04833,
         "score": 0.9999999,
         "emotions": [
           {
             "emotion": "neutral",
             "score": 0.99958
           },
           {
             "emotion": "sad",
             "score": 0.0004020398
           },
           {
             "emotion": "happy",
             "score": 8.603504e-06
           },
           {
             "emotion": "surprise",
             "score": 8.076798e-06
           },
           {
             "emotion": "disgust",
             "score": 6.653509e-07
           },
           {
             "emotion": "angry",
             "score": 6.14346e-07
           },
           {
             "emotion": "fear",
             "score": 7.33713e-10
           }
         ]
       },
       "meta": {},
       "normalized_id": "2_bd323f5t8f66ph0eafp0.png"
     }
   ],
   "next_page": "3"
 }

Search Face in Gallery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following request searches the gallery ``galleryname`` for faces similar to a detected face (detection result stored in ``memcached``) with threshold similarity equal to 0.5. Relevant HTTP API request: ``/galleries/<gallery>/faces`` with enabled ``detection:id`` and ``similarity`` filters.

.. rubric:: Request

::

 curl -s 'http://localhost:18411/v2/galleries/galleryname/faces?detection:bd3hv4tt8f66ph0eag1g=0.5&limit=1' | jq

.. rubric:: Response

::

 {
   "faces": [	
     {
       "id": {
         "gallery": "galleryname",
         "face": 2
       },
       "features": {
         "gender": {
           "gender": "FEMALE",
           "score": -2.6415923
         },
         "age": 26.04833,
         "score": 0.9999999,
         "emotions": [
           {
             "emotion": "neutral",
             "score": 0.99958
           },
           {
             "emotion": "sad",
             "score": 0.0004020398
           },
           {
             "emotion": "happy",
             "score": 8.603504e-06
           },
           {
             "emotion": "surprise",
             "score": 8.076798e-06
           },
           {
             "emotion": "disgust",
             "score": 6.653509e-07
           },
           {
             "emotion": "angry",
             "score": 6.14346e-07
           },
           {
             "emotion": "fear",
             "score": 7.33713e-10
           }
         ]
       },
       "meta": {},
       "normalized_id": "2_bd323f5t8f66ph0eafp0.png",
       "confidence": 0.9999
     }
   ],
   "next_page": "There are more than 1 results, but pagination is not supported when filtering by FaceN"
 }


The following request searches the gallery ``galleryname`` for faces similar to a given face in the same gallery with threshold similarity equal to 0.5. Relevant HTTP API request: ``/galleries/<gallery>/faces`` with enabled ``face:<gallery>/<db_id>`` and ``similarity`` filters.

::

 curl -s 'http://localhost:18411/v2/galleries/galleryname/faces?face:galleryname/1=0.1&limit=1' | jq

::

 {
   "faces": [
     {
       "id": {
         "gallery": "galleryname",
         "face": 2
       },
       "features": null,
       "meta": {},
       "confidence": 0.999
     }
   ],
   "next_page": "There are more than 1 results, but pagination is not supported when filtering by FaceN"
 }

Compare Faces
^^^^^^^^^^^^^^^^^^^

The following requests compare a pair of faces and return a probability of their belonging to the same person. Relevant HTTP API method: ``/verify POST``.

The first request compares 2 results of the ``/detect POST`` method, stored in ``memcached``. 

.. rubric:: Request #1

::

 curl -s 'http://localhost:18411/v2/verify?face1=detection:bd3hv4tt8f66ph0eag1g&face2=detection:bd3hv8dt8f66ph0eag2g' | jq

.. rubric:: Response

::

 {
   "confidence": 0.92764723
 }

The 2nd request compares a result of the ``/detect POST`` method and a face in a gallery.

.. rubric:: Request

::

 curl -s 'http://localhost:18411/v2/verify?face1=detection:bd3hv4tt8f66ph0eag1g&face2=face:galleryname/2' | jq

.. rubric:: Response

::

 {
   "confidence": 0.999996
 }