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 should 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 standalone deployment, you can access Tarantool by default only locally (127.0.0.1). If you want to access Tarantool remotely, change the Tarantool configuration file.

Each API request to Tarantool contains the following parameters:

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

  • :name: the gallery name.

    Tip

    To list gallery names on a shard, type in the following command in the address bar of your browser (see List Galleries for details):

    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.

  • :id: the face id.

Add Face

Request

POST /:ver/:name/add/:id

Body: a raw feature vector (facen)

Returns:

  • HTTP 200 and empty body if success.
  • HTTP 409 if a face with the same id already exists in the gallery.
  • HTTP with a status other than 200 and error description in the body if failure.

Example

curl -s -D - 'http://localhost:8001/v1/my_gal/add/1234' --data-binary @3827305024709134.facen

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

Get Facen

Request

GET /:ver/:name/get/:id

Returns:

  • A JSON representation of the face with its id and base64 encoded facen if 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 if failure.

Tip

To convert a facen from base64 to a binary file, execute:

echo 'facen in base64' |base64 -d> facen

Example

curl -s -D - 'http://localhost:8001/v1/my_gal/get/1234' HTTP/1.1 200 Ok Content-length: 1754 Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc) Connection: keep-alive {"facen":"BFa9PWNlS7215fI98ETQvJkxML2hUFY9cF\/Tu9ZjnLx\/uVc9EzWSPQTsR7zoysI8+4PSPIsjnr2GV1M8eFMKvfn9mjsPPjA8ZXoNvTEsSr0rJkM9MR0IPINXSj3Em0s9awm5Oos5SD380a693GroPBz6nzxQMDQ9HdOjPd7QhDxUIzC+g90sPUWUDLwjk7U9cpWkPZ83 rTyEDNm8Ti\/0ve4Trr1rnQA+Yc\/KvJzqnbzOPSG998CKPBFpAr77kFO9BonDvK9B0buvjAq9Q7A\/u6awnTw0lvy80QZcvRFQAz0BdH498hF6vQKRcDy77c08mGRkvQ305DomnBM9XSqwvN54GT0ClFO9a+kWvhp7iT3uqqU9v1+\/vYhzm7uREt091douuyDKRr2PcIG9Uc8xPVJnvzt5T309NicxPD9SAr3f6sO8UmlhvRMI67wlTte880wYvUF8o7xg4\/g8aqNQu\/AAWD2z59C9CQCrPepF7Dy8qUa9iCczPfKv+Dy+bRo9KhyYPZfY0b1xtbY7nKXLuvYFbr0g8rM86o0QPRCKOj1a7rU9bd+3Pbqs7LslJcO9bBh+vVYeUr3S95Y9Wtg5PUZnRr0D0G08lkRkveImPDx4iQ084Qy1vKRBjj3uf4W85qx+vREFX7uccQ++5mMMvetNAL25b409P0GQvDIGLz3mHqg9ca\/Guv2beTy56wg7p\/hTPdxQgr0jxQQ9Ud0CPZcx\/LtRLiU9bECQvUnvszpMVcM8b3OovURPET3JdHs9LyQUPsc9JzvW1ZQ7y2ySPdN4Xb0xi9c8X7UevRqjVL0MLpE9PoQpvFxxjD2NCDO81jH\/PF1KFTzc3pc7qpaFPXxuPb2tjsY9iA5lPR1NoT1+Uuu7G6gpu727wTwo6ii8iaH+PI1WY72D9QG+8lhAPUegx71VsFs8ajQLvOdekrzGqAg+zhPLvbjyNDxaI1E9Wkj\/O1307D1ZMSk9IxqGvYCvFb1bE429hZF4vewikzwDbfG8wwYNPiQn4L2NV6Q9VKrvPTjwTr3dlG05jck+vZ\/KID1+n8Y8qpvnvOJjBj2P4+w8IJGgvROAfz1S4ve8QEouvQ5CkDu0OTI8\/v\/pvFrK5b3bkIO82LVBPcf2Yr0aGaU9RArUvEecJz1r8zk87U4vvC65ljz6kRS956U2PH6JMT5nfAg7KX7qPBz7Ejy60vk9\/iEPPYw8pT3Mfvk8UQYyPUCG+TyD5CO90c6nvSVLvDwRJSW9C3udvDORMz3zqtU8yd+0PXrubj3u9pQ9cGZIPVjlqTz6eIs8Z4wsPIjEIT3gnqI9kjhTPRJ8b73crA492KKIvSvpEz3ROrs9M+ZrO3RDOrwPpgG9+buePbiwi726dSs9k\/iVvZjEhT3W0B69IRojvQGUVj2J6vQ9FiDhPNRUO70bcum9fOOvPKA\/y7yB9wq9ntsBPYL6XL0wgkw7nLu6O\/\/USz1EoUg9JKE9PLDzNL0Pns49fPVyPJfZaj2g6pi8MuZePV0xQLxkR4W9pEe7vYTv7jytv567nakpPcCHZbsfjx89jPENPW0x87vr3Wi84L9mvSGeFL2hsBo9HBI2vXiEJr2uIQW7L0FsPU2w8jz2chi9FB5nvFcj9rknTha9qxCoPb0Qu72sIik9Hn4FvE\/8JL02Vh0879v\/O6weQjxpD7k85Kj2PGb0ej0V6xS8\/4EvPXmv3z0=","id":1234}

Remove Face

Warning

Removing a face from Tarantool will not remove it from MongoDB.

Request

DELETE /:ver/:name/del/:id

Returns:

  • HTTP 200 and empty body if 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 if failure.

Example

curl -s -D - -X DELETE 'http://localhost:8001/v1/my_gal/del/1234'

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

List Faces

Request

GET /:ver/:name/list/:start_id/:count
:start_id: the minimum face_id in the response.
:count: the maximum number of faces in the response.

Returns:

  • A JSON array with faces, and the next page URL if success. Each face is provided with its id, base64 encoded facen and the name of a Tarantool space where the face is located (linear, preindex, or indexed). The next page URL should be passed as :start_id in another API request to get the next page of results.
  • HTTP with a status other than 200 and error description in the body if failure.

Example

curl -s -D - 'http://localhost:8001/v1/my_gal/list/0/1' HTTP/1.1 200 Ok Content-length: 1795 Server: Tarantool http (tarantool v1.7.3-673-g23cc4dc) Connection: keep-alive {"faces":[{"id":1234,"space":"linear","facen":"BFa9PWNlS7215fI98ETQvJkxML2hUFY9cF\/Tu9ZjnLx\/uVc9EzWSPQTsR7zoysI8+4PSPIsjnr2GV1M8eFMKvfn9mjsPPjA8ZXoNvTEsSr0rJkM9MR0IPINXSj3Em0s9awm5Oos5SD380a693GroPBz6nzxQMDQ9HdO jPd7QhDxUIzC+g90sPUWUDLwjk7U9cpWkPZ83rTyEDNm8Ti\/0ve4Trr1rnQA+Yc\/KvJzqnbzOPSG998CKPBFpAr77kFO9BonDvK9B0buvjAq9Q7A\/u6awnTw0lvy80QZcvRFQAz0BdH498hF6vQKRcDy77c08mGRkvQ305DomnBM9XSqwvN54GT0ClFO9a+kWvhp7iT3uqqU9v1+\/vYhzm7uREt091douuyDKRr2PcIG9Uc8xPVJnvzt5T309NicxPD9SAr3f6sO8UmlhvRMI67wlTte880wYvUF8o7xg4\/g8aqNQu\/AAWD2z59C9CQCrPepF7Dy8qUa9iCczPfKv+Dy+bRo9KhyYPZfY0b1xtbY7nKXLuvYFbr0g8rM86o0QPRCKOj1a7rU9bd+3Pbqs7LslJcO9bBh+vVYeUr3S95Y9Wtg5PUZnRr0D0G08lkRkveImPDx4iQ084Qy1vKRBjj3uf4W85qx+vREFX7uccQ++5mMMvetNAL25b409P0GQvDIGLz3mHqg9ca\/Guv2beTy56wg7p\/hTPdxQgr0jxQQ9Ud0CPZcx\/LtRLiU9bECQvUnvszpMVcM8b3OovURPET3JdHs9LyQUPsc9JzvW1ZQ7y2ySPdN4Xb0xi9c8X7UevRqjVL0MLpE9PoQpvFxxjD2NCDO81jH\/PF1KFTzc3pc7qpaFPXxuPb2tjsY9iA5lPR1NoT1+Uuu7G6gpu727wTwo6ii8iaH+PI1WY72D9QG+8lhAPUegx71VsFs8ajQLvOdekrzGqAg+zhPLvbjyNDxaI1E9Wkj\/O1307D1ZMSk9IxqGvYCvFb1bE429hZF4vewikzwDbfG8wwYNPiQn4L2NV6Q9VKrvPTjwTr3dlG05jck+vZ\/KID1+n8Y8qpvnvOJjBj2P4+w8IJGgvROAfz1S4ve8QEouvQ5CkDu0OTI8\/v\/pvFrK5b3bkIO82LVBPcf2Yr0aGaU9RArUvEecJz1r8zk87U4vvC65ljz6kRS956U2PH6JMT5nfAg7KX7qPBz7Ejy60vk9\/iEPPYw8pT3Mfvk8UQYyPUCG+TyD5CO90c6nvSVLvDwRJSW9C3udvDORMz3zqtU8yd+0PXrubj3u9pQ9cGZIPVjlqTz6eIs8Z4wsPIjEIT3gnqI9kjhTPRJ8b73crA492KKIvSvpEz3ROrs9M+ZrO3RDOrwPpgG9+buePbiwi726dSs9k\/iVvZjEhT3W0B69IRojvQGUVj2J6vQ9FiDhPNRUO70bcum9fOOvPKA\/y7yB9wq9ntsBPYL6XL0wgkw7nLu6O\/\/USz1EoUg9JKE9PLDzNL0Pns49fPVyPJfZaj2g6pi8MuZePV0xQLxkR4W9pEe7vYTv7jytv567nakpPcCHZbsfjx89jPENPW0x87vr3Wi84L9mvSGeFL2hsBo9HBI2vXiEJr2uIQW7L0FsPU2w8jz2chi9FB5nvFcj9rknTha9qxCoPb0Qu72sIik9Hn4FvE\/8JL02Vh0879v\/O6weQjxpD7k85Kj2PGb0ej0V6xS8\/4EvPXmv3z0="}],"next":5678}