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 /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.

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