HTTP API — MARV Robotics 19.07.0 documentation

# 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).