HTTP API

The API used between frontend and backend currently serves also for integration with other services. We are aware that this is suboptimal and will provide a proper versioned API in one of the next releases. Meanwhile this works and migration will be minimal.

To work with the API on the command line it is handy to have curl and jq.

sudo apt-get install curl jq

Set an environment variable for the API.

export MARV_API=http://localhost:8000/marv/api

Auth

For some API calls you need to be authenticated, let’s get a token, and set handy environment vars.

echo -n "Enter username: "; read -s MARV_USER && echo && \
echo -n "Enter password: "; read -s MARV_PASS && echo && \
TOKEN=$(curl -s -X POST -H "Content-Type: application/json" \
  -d '{"username": "'$MARV_USER'", "password": "'$MARV_PASS'"}' \
  $MARV_API/auth | jq -r .access_token) && \
echo $TOKEN

Listing

MARV knows two kind of ids for dataset.

  1. setid; a random 128 bit integer, base32 encoded without padding chars, e.g. h27zmwsdzcnmu6kqncwdhhvrva
  2. id; id of the dataset within the database, e.g. 42

While the set id is unique for all times and across sites, for many interactions it is more efficient to use the database id.

Fetch id of all datasets:

curl $MARV_API/collection |jq '.listing.widget.data.rows[] | .id'

And likewise for setid:

curl $MARV_API/collection |jq '.listing.widget.data.rows[] | .setid'

Filter

curl -G \
  --data-urlencode \
  'filter={"name": {"op": "substring", "val": "leica"}}' \
  $MARV_API/collection \
  |jq '.listing.widget.data.rows[] | .setid'
curl -G \
  --data-urlencode \
  'filter={"tags": {"op": "all", "val": ["bar", "foo"]}}' \
  $MARV_API/collection \
  |jq '.listing.widget.data.rows[] | .setid'
curl -G \
  --data-urlencode \
  'filter={"tags": {"op": "any", "val": ["bar", "foo"]}}' \
  $MARV_API/collection \
  |jq '.listing.widget.data.rows[] | .setid'

List of dataset files

curl -X POST \
     -H "Content-Type: application/json" \
     -d "[42]" \
     $MARV_API/file-list

output:

{
  "paths": [
    "/scanroot/scan_odom_map_test.bag",
  ],
  "urls": [
    "dataset/h27zmwsdzcnmu6kqncwdhhvrva/0",
  ]
}

Download

First file of dataset

curl -OJ $MARV_API/dataset/h27zmwsdzcnmu6kqncwdhhvrva/0

Comment

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"42": {"add": ["comment 1", "comment 2"]}}' \
     $MARV_API/comment

output:

{}

Delete

curl -X DELETE \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d "[1,2]" \
     $MARV_API/dataset

output:

{}

Deletion is idempotent.

Tag

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"bags": {"add": {"foo": [42]}, "remove": {"bar": [17,42]}}}' \
     $MARV_API/tag
{}

Tagging is idempotent, missing tags are created, unused tags are not automatically cleaned up (see Maintenance).