Direct API Requests to Tarantool

You can use HTTP API to extract data directly from the Tarantool Database.

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:

cat /etc/tarantool/instances.enabled/FindFace.lua

##8001:
FindFace.start("127.0.0.1", 8001)

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.

API requests to Tarantool may contain the following parameters in path segments:

  • :ver: API version (v2 at the moment).

  • :name: gallery name.

    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 Face

POST /:ver/faces/add/:name

Parameters in body:

JSON-encoded array of faces with the following fields:

  • "id": face id in the gallery, uint64_t,
  • "facen": raw feature vector, base64,
  • "meta": face 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:8001/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 Face

POST /v2/faces/delete/:name

Parameters in body:

JSON-encoded array of face ids to be removed

Returns:

  • HTTP 200 and empty body on success.
  • HTTP 404 if a face 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:8001/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 Face Metadata and Feature Vector

POST /v2/faces/update/:name

Parameters in body:

JSON-encoded array with faces with the following fields:

  • "id": face 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 face parameters, including not updated, on success.
  • HTTP 404 and error description if a face 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:8001/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 faces in a gallery.

Example

Request

curl -D - -s -X POST http://localhost:8001/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
    }
  ]
}