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.

In this section:

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:

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, alter 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 body images uploaded to the card index.

  • ffsec_body_clusters: centroids of body clusters.

  • ffsec_car_events: feature vectors extracted from cars detected in the video.

  • ffsec_car_objects: feature vectors extracted from car images uploaded to the card index.

  • ffsec_car_clusters: centroids of car clusters.

  • ffsec_face_events: feature vectors extracted from faces detected in the video.

  • ffsec_face_objects: feature vectors extracted from face images uploaded to the card index.

  • ffsec_face_clusters: centroids of face clusters.

  • ffsec_user_face: feature vectors extracted from the FindFace Multi users’ photos for face-based authentication.

Tip

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

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

The same command on the console is as such:

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

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

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

POST /:ver/faces/add/:name

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.

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.

Example

Request

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",

    }
  }
]

Response

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

Remove Object

POST /v2/faces/delete/:name

Parameters in body:

JSON-encoded array of object ids to be removed

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.

Example

Request

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

Response

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

Edit Object Metadata and Feature Vector

POST /v2/faces/update/:name

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.

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.

Example

Request

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

Response

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

POST /v2/galleries/list

Returns:

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

Example

Request

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

Response

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
    }
  ]
}