Menu

Back-end API Documentation

Back-end Dashboard

Through your back-end account you get access to a web dashboard that includes a section with authentication secrets. Those secrets are used to encode authentication tokens (as JWT) to be passed to the SDK, and to access the back-end API.

The base URI for all requests is https://api.motion-tag.de.

Storyline Synchronization

Endpoint for synchronization of the complete storyline.

The storyline is an endless stream of chronologically sorted entries. New entries are appended continuously by the MotionTag analysis process.

This endpoint implements a mechanism to retrieve the complete stream and continuously poll for new entries. The responses are grouped into pages of reasonable size. A page includes a link to the next page, unless it is empty because there are currently no more entries available.

Make an initial request without the page parameter to get the first available page. If there is any data, the response page will include a link to the next page. Loop to request the next page, until an empty page is reached. Once an empty page is reached, pause for a short time and then retry to load the same page again.

Example initial request without page parameter and response with entries:

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"
  }
}

Store the received entries and immediately afterwards request the next page given in links.next. Note that the value of page[after] has no meaning beyond being used by the server to determine the next page.

Example request when there are no more entries:

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

{
  data: []
}

Pause for a short time (e.g. 1 minute) and then request the latest URL from links.next again.

Authentication

Every request to the sync endpoint must be authenticated with an authorization header with a JWT, encrypted with the shared token_secret. The JWT must include the claims iss and exp in the payload. The issuer is the tenant key of the consumer. The expiration date (unix epoch) should be set to a short time into the future to avoid a lost token being useful for a long time.

{
  "iss" : "the-tenant",
  "exp" : 1533040854
}

The authorization HTTP header will then look somehow like this:

Authorization: Bearer abc123.def456.gehi7890

In the back-end dashboard you can download an encoded token for experimenting with the API.