Skip to content

REST Interface Specification

Jump to bottom
Luca Di Leo edited this page Oct 5, 2020 · 26 revisions

Introduction

The purpose of this document is to define the REST interface of the Registry component

Authentication

POST /users/authenticate

Authenticate with the server.

Request body:

{ 
    "username": "test", 
    "password": "12345678"
}

Response:

{ 
    "id": "1", 
    "token": "[...]"
}

The token is a JWT token.

Making Authenticated Requests

To make requests to a protected endpoint, you must pass the header:

Authentication: Bearer <token>

Share

POST /share/init

Initializes a new share transaction and creates a new upload batch. It allows the client to create a new organization and dataset in one call.

Request body:

tag=organization/dataset

The tag parameter is optional. If not provided the registry will use the current user default organization and auto-generate a new dataset for the batch.

Response:

{
    "token": "[..]",
    "tag": "organization/dataset"
}

This token identifies the batch and allows to perform the uploads using the upload endpoint

POST /share/upload/[token]

Adds a new file to a specific batch in a certain path.

The request body contains two fields: file and path. The first one is the file to upload, the latter is the path where to upload.

POST /share/commit/{token}

Closes a batch, no more uploads are allowed.

Organization

Organization example:

{ 
    "slug": "test",
    "name": "Test org", 
    "description": "This organization has got the best datasets!",
    "creationDate": "2019-04-23T18:25:43.511Z",
    "isPublic": true,
    "owner": "micky"
}

GET /orgs/

List all organizations

GET /orgs/{org}

Get details of organization

POST /orgs/

Create new organization

Curl Example

curl --location --request POST 'https://localhost:44359/orgs/' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IjRkODgwMDlmLTQ4NjItNDM3Ni1hYjRhLWNlYzZjMWI0OTUxNCIsImFkbWluIjoiVHJ1ZSIsIm5iZiI6MTU5ODg5MzQ0OCwiZXhwIjoxNTk5NDk4MjQ4LCJpYXQiOjE1OTg4OTM0NDh9.ttFMcFsok4USUU-jBcGa34rD5LOdOyshoTw8Mvqk5Ww' \
--form 'slug=test' \
--form 'name=Test org' \
--form 'description=This organization has got the best datasets!' \
--form 'isPublic=true'

DELETE /orgs/{org}

Delete organization and all its contents

Dataset

Dataset example:

{
    "id": "odm_data_aukerman",
    "name": "ODM data Aukerman",
    "description": "Here it is a realy good dataset",
    "creationDate": "2019-04-23T18:25:43.511Z",
    "license": "Creative Commons Zero v1.0 Universal",
    "size": 340123382,
    "objectsCount": 194,
    "lastEdit": "2020-05-12T12:54:21.135Z",
    "meta": { 
        "key1": "value1", 
        "key2": "value2" 
    },
}

GET /orgs/{org}/ds/{dataset}

Get details of dataset

POST /orgs/{org}/ds/{dataset}

Create new dataset

PUT /orgs/{org}/ds/{dataset}

Edit dataset

DELETE /orgs/{org}/ds/{dataset}

Delete dataset and all its contents

GET /orgs/{org}/ds/{dataset}/batches

Get the loading batches of the dataset

Example:

[
    {
        "token": "Zg0GlCyth03Lp9sWnQAP7CeYgUyJ6aH9",
        "userName": "admin",
        "start": "2020-08-25T18:54:10.4307917",
        "end": "2020-08-25T19:15:26.8173472",
        "entries": [
            {
                "path": "IMG_20160904_130800.jpg",
                "hash": "6359eeb281646f69282b334bf7799ace39ea3dde8f5b7aeb171da53221e85ecc",
                "type": 6,
                "size": 1636264,
                "addedOn": "2020-08-25T19:10:56.1774135"
            },
            {
                "path": "IMG_20160904_130804.jpg",
                "hash": "dfddecc1f7f9f3a885a8576d2f36922926106379b6e54bc0d5979e410aa78946",
                "type": 6,
                "size": 1547671,
                "addedOn": "2020-08-25T19:11:57.7840843"
            }
        ]
    }
]

Objects

Object of type image example:

Should match ddb info --format json DJI_0287.JPG

{
  "id": 123,
  "path": "path/to/DJI_0287.JPG",
  "mtime": 1481082134,
  "hash": "08e395b4e17afb4572c906d5b5bb1611165d2feb",
  "depth": 2,
  "size": 4024770,
  "type": 3, 
  "meta": {
    "cameraPitch": -89.9000015258789,
    "cameraRoll": 0.0,
    "cameraYaw": 45.0,
    "captureTime": 1466717519000.0,
    "focalLength": 3.4222222222222225,
    "focalLength35": 20.0,
    "height": 2250,
    "make": "DJI",
    "model": "FC300S",
    "orientation": 1,
    "sensor": "dji fc300s",
    "sensorHeight": 3.4650000000000003,
    "sensorWidth": 6.16,
    "width": 4000
  },
  "point_geom": {
    "crs": {
      "properties": {
        "name": "EPSG:4326"
      },
      "type": "name"
    },
    "geometry": {
      "coordinates": [
        -91.99455988888889,
        46.842607083333334,
        198.31
      ],
      "type": "Point"
    },
    "properties": {},
    "type": "Feature"
  },
  "polygon_geom": {
    "crs": {
      "properties": {
        "name": "EPSG:4326"
      },
      "type": "name"
    },
    "geometry": {
      "coordinates": [
        [
          [
            -91.9946977338554,
            46.842964997231924,
            158.51000076293946
          ],
          [
            -91.9950761686676,
            46.84271189347757,
            158.51000076293946
          ],
          [
            -91.99442040670127,
            46.84225026546232,
            158.51000076293946
          ],
          [
            -91.99404197212225,
            46.84250336706982,
            158.51000076293946
          ],
          [
            -91.9946977338554,
            46.842964997231924,
            158.51000076293946
          ]
        ]
      ],
      "type": "Polygon"
    },
    "properties": {},
    "type": "Feature"
  }
}

Both the point_geom and polygon_geom follow the GeoJson specification

https://geojson.io/ and https://en.wikipedia.org/wiki/GeoJSON

Hierarchy information can be inferred from path. Efficient queries can be further performed using "depth".

Object of type folder example:

{
    "type": 1,
    "path": "path/to"
    ....
}

Has a parent at "path".

GET /orgs/{org}/ds/{dataset}/info

List objects inside dataset (file infos)

GET /orgs/{org}/ds/{dataset}/obj

Get object data (binary download), only for content files: images, etc...

POST /orgs/{org}/ds/{dataset}/obj

Create new object

DELETE /orgs/{org}/{dataset}/obj

Delete object

Clone this wiki locally