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.
- setid; a random 128 bit integer, base32 encoded without padding chars, e.g.
h27zmwsdzcnmu6kqncwdhhvrva
- 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",
]
}
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).