Backend documentation

Overview

The MOTIONTAG backend API provides endpoints meant to be consumed by other backends, for example to download analysis results in bulk. In order to access it, you need to be given access by MOTIONTAG staff. As part of that you will be provided with a dedicated domain, which also serves as the base URL for the API.

Note that once you have access, you can see a customized version of this documentation under https://{dedicated_domain}/developer/backend.

The API tries to follow the JSON API standard.

Authentication

Every request must be authenticated with a JSON Web Token, signed with the shared token_secret which is available on the admin dashboard under "Authentication tokens". This JSON Web Token must include the claims sub (subject) and exp (expires) in the payload.

The sub claim is a string with an endpoint specific scope. The exp claim is a timestamp expressed as integer unix epoch and should be set to a short time into the future to avoid a lost token being useful for a long time.

{
  "sub": "example_scope",
  "exp": 1234567890
}

The JSON Web Token should be sent as HTTP Authorization header like this:

Authorization: Bearer abc123.def456.gehz7890

Storyline synchronization API

Endpoint for synchronization of the complete storyline of one tenant. Meant to be implemented by customers that run their own service.

The storyline is an endless stream of chronologically sorted entries. New entries are appended continuously by the Modedetection. This endpoint implements a mechanism to retrieve the complete stream, grouped into pages of reasonable size, by adding a link to the next page of data to a response that contains entries. An initial request without the special page parameter will return the first available page, and include a link to the next page. When the end is reached, an empty page without a next link is returned. In this case the consumer should pause for a short time and then retry to load the same page again.

For authentication, the endpoint specific scope to include in the JSON Web Token in the sub claim is "sync":

{
  "sub": "sync",
  "exp": 1234567890
}

Example initial request without page parameter:

GET /sync/storyline

{
  "data": [
    {
      "type" : "Track",
      "id" : "8861e1e2-abd0-41cc-9b3d-f8c2d2613cf4",
      "attributes" : {
        "user_id" : "d28907c7-0846-461f-950e-9d40f2ca418c",
        "created_at" : "2018-01-01T16:00:00Z",
        "started_at" : "2018-01-01T14:00:00Z",
        "started_at_timezone" : "Europe/Zurich",
        "finished_at" : "2018-01-01T15:00:00Z",
        "finished_at_timezone" : "Europe/Zurich",
        "geometry" : {
           "type" : "LineString",
           "coordinates" : [
              [
                 1,
                 1.5
              ],
              [
                 1.5,
                 2
              ]
           ]
        },
        "track_mode" : "bicycle",
        "track_length_in_meters" : 5000
      }
    },
    {
       "type" : "Stay",
       "id" : "c862b09b-2786-4be3-b0d6-90997783a343",
       "attributes" : {
         "user_id" : "437b0a94-d495-4e4e-96fb-fe1783b5c95e",
         "created_at" : "2018-01-01T16:00:00Z",
         "started_at" : "2018-01-01T14:00:00Z",
         "started_at_timezone" : "Europe/Zurich",
         "finished_at" : "2018-01-01T15:00:00Z",
         "finished_at_timezone" : "Europe/Zurich",
         "geometry" : {
            "type" : "Point",
            "coordinates" : [
               1,
               1.5
            ]
         },
         "stay_purpose" : "study"
       }
    },
    "..."
  ],
  "links": {
    "next" : "https://api.motion-tag.de/sync/storyline?page[after]=abc123"
  }
}

The consumer is expected to store the received entries and immediately afterwards request the next page given in links.next. The value of page[after] has no meaning beyond being used by the server to determine the next page.

Example request with no more data:

GET /sync/storyline?page[after]=abc123

{
  "data": []
}

The consumer should pause for a short time and then request the same URL again.

Dump downloads

Data dumps available on the admin dashboard interface under "Dumps" can be downloaded from this endpoint by using their filename. The filename is chosen automatically on creation and consists of the dump type, its user and date criteria, and the format. Note that the API currently only provides the ability to download dumps, not to create or delete them.

For authentication, the endpoint specific scope to include in the JSON Web Token in the sub claim is "dumps":

{
  "sub": "dumps",
  "exp": 1234567890
}

GET /dumps/ExampleDump.SomeProject.2020-01-01--2020-01-31.csv.gz

Alternatively to using an HTTP header the dump downloads can also be authenticated with a URL parameter.

GET /dumps/ExampleDump.SomeProject.2020-01-01--2020-01-31.csv.gz?jwt=abc123.def456.gehz7890