Skip to content

Web API

Jump to bottom
Andrei Tomashpolskiy edited this page Jul 9, 2019 · 13 revisions

Web API provides the means for building a browser-based user and administrative consoles for the Octopus server.

Example URLs below assume that the Jetty/Jersey configuration is like this:

jetty:
  context: /
  connectors:
    - type: http
      port: 9998

jersey:
  urlPattern: /rest/*

Web socket Admin API

Endpoint: ws://<host>:<port>/<jetty-context>/ws/admin

With the aforementioned Jetty configuration the Admin WS endpoint will be ws://<host>:9998/ws/admin

Admin API sends the following messages:

  1. List of known slave servers
{
  "id" : <unique-numeric-id>,
  "type" : "slaves",
  "slaves" : [ "192.168.1.132" ]
}
  1. Latest time sync result with master
{
  "id" : <unique-numeric-id>,
  "type" : "mastersync",
  "syncResult" : {
    "finished" : 1557831685908,
    "delay" : 0,
    "error" : "Connection refused: 192.168.1.132:9992"
  }
}

Synchronization result contains three fields:

  • finished, which is the result's timestamp in UTC epoch milliseconds
  • delay, which is a (signed) integer, designating the number of milliseconds, that it takes on average for the message to reach the remote server; this value is 0, when there was a synchronization failure
  • error, which is a textual description of the synchronization failure; this value is null, if the synchronization finished successfully
  1. List of known clients (i.e. mobile apps)
{
  "id" : <unique-numeric-id>,
  "type" : "clients",
  "syncResultsByHeadsetId" : {
    "EPOCPLUS-3B9ADF08": [ {
      "finished" : 1557831685908,
      "delay" : 1,
      "error" : null
    } ]
  }
}

syncResultsByHeadsetId field is a dictionary with keys being the headset ID and values being arrays of synchronization results (from the least to the most recent; currently, the array will contain only the single, most recent result). Synchronization result contains three fields:

  • finished, which is the result's timestamp in UTC epoch milliseconds
  • delay, which is a (signed) integer, designating the number of milliseconds, that it takes on average for the message to reach the client; this value is 0, when there was a synchronization failure
  • error, which is a textual description of the synchronization failure; this value is null, if the synchronization finished successfully
  1. List of clients' mood states
{
  "id" : <unique-numeric-id>,
  "type" : "clientstates",
  "statesByHeadsetId" : {
    "EPOCPLUS-3B9ADF08": [ {
      "state": "NEUTRE",
      "since": 1557831685908
    } ]
  }
}

statesByHeadsetId field is a dictionary with keys being the headset ID and values being arrays of state change events, received from the client (from the least to the most recent; currently, the array will contain only the single, most recent event). State change event contains two fields:

  • state, which is a literal name of the net.manaty.octopusync.api.State gRPC enum; possible values are: NEUTRE, FAIBLE_PLAISIR, PLAISIR_INTENSE, FRISSON_MUSICAL
  • since, which is the event's timestamp in UTC epoch milliseconds
  1. List of known headsets
{
  "id" : <unique-numeric-id>,
  "type" : "headsets",
  "statusByHeadsetId" : {
    "EPOCPLUS-3B9ADF08" : {
      "connected" : true,
      "clientConnectionCreated" : true,
      "code": "E1",
      "info" : {
        "battery" : 4,
        "signal" : 2,
        "af3" : 0.0,
        "f7" : 2.0,
        "f3" : 1.0,
        "fc5" : 0.0,
        "t7" : 4.0,
        "p7" : 0.0,
        "o1" : 4.0,
        "o2" : 4.0,
        "p8" : 2.0,
        "t8" : 4.0,
        "fc6" : 4.0,
        "f4" : 0.0,
        "f8" : 4.0,
        "af4" : 4.0
      }
    },
    "EPOCPLUS-HU74KZ12" : {
      "connected" : false,
      "clientConnectionCreated" : false,
      "code": null
    }
  }
}

statusByHeadsetId field is a dictionary with keys being the headset ID and values being the current headset status. Headset status contains two fields:

  • connected, which is a boolean indicator of whether the headset is connected to the Emotiv PRO software or not (information is collected from the Emotiv PRO API)
  • clientConnectionCreated, which is a boolean indicator of whether a client connection is currently established and open for this headset
  • code, which is the human-readable short code for this headset; might be null, if this headset has not been listed in the configuration
  • info, which is an object, containing information about the connected headset (battery level, overall signal quality, individual contacts); it will be absent or null, if connected == false.

REST API

Admin operations

Starting the experience

Endpoint: http://<host>:<port>/<jetty-context>/<jersey-context>/admin/experience/start

With the aforementioned Jetty/Jersey configuration an example URL will be http://<host>:9998/rest/admin/experience/start.

This is a POST operation. Request body is ignored.

Stopping the experience

Endpoint: http://<host>:<port>/<jetty-context>/<jersey-context>/admin/experience/stop

With the aforementioned Jetty/Jersey configuration an example URL will be http://<host>:9998/rest/admin/experience/stop.

This is a POST operation. Request body is ignored.

Sending a manual trigger

Endpoint: http://<host>:<port>/<jetty-context>/<jersey-context>/admin/trigger

With the aforementioned Jetty/Jersey configuration an example URL will be http://<host>:9998/rest/admin/trigger.

This is a POST operation. Request body is treated as the trigger's message.

Indicating, if music is on/off

Endpoints:

  • http://<host>:<port>/<jetty-context>/<jersey-context>/admin/music/on
  • http://<host>:<port>/<jetty-context>/<jersey-context>/admin/music/off

With the aforementioned Jetty/Jersey configuration an example URL will be http://<host>:9998/rest/admin/music/on.

This is a POST operation. Request body should be empty.

Reporting

Generating a report

Endpoint: http://<host>:<port>/<jetty-context>/<jersey-context>/report/generate[?headset_id=<headset-id>&from=<HH:mm:ss>&to=<HH:mm:ss>]

With the aforementioned Jetty/Jersey configuration an example URL will be http://<host>:9998/rest/report/generate?headset_id=EPOCPLUS-4A2C0686&from=10:30&to=11:00 (generate report for headset EPOCPLUS-4A2C0686 and time interval today, 10:30:00-11:00:00)

Specifying the time interval is optional. If from is omitted, then the start of the day (12:00:00 AM) is used as the beginning of the interval. If to is omitted, then the start of the next day is used as the end of the interval.

Specifying the headset ID is optional. If headset_id query parameter is omitted, then the server will generate reports for all headsets in the time interval (i.e. all headsets, for which there exists at least one event with today's timestamp in the database).

The response is a JSON dictionary, where the key is the headset ID and the value is the name of the report (see information on retrieving the generated report below).

E.g.:

/report/generate?headset_id=<headset-id> will output a single report with all events for a given headset for today.

{
  "EPOCPLUS-4A2C0686":"EPOCPLUS-4A2C0686-20190520000000-20190521000000.csv"
}

/report/generate will output multiple reports, each containing all events for some headset for today.

{
  "EPOCPLUS-4A2C0686":"EPOCPLUS-4A2C0686-20190520000000-20190521000000.csv",
  "EPOCPLUS-4A3D0510":"EPOCPLUS-4A3D0510-20190520000000-20190521000000.csv"
}

Retrieving a generated report

Endpoint: http://<host>:<port>/<jetty-context>/<jersey-context>/report/get/<report-name>

With the aforementioned Jetty/Jersey configuration an example URL will be http://<host>:9998/rest/report/get/EPOCPLUS-4A2C0686-20190520000000-20190521000000.csv

The response is the report's content in plain text.

Clone this wiki locally