Socket connection API reference


The API communicates entirely in JSON format. Therefore all parameters for certain functions have to be passed within a JSON object.

{
    [parameter name]: [value]
}

All responses are as well in JSON format. Some requests result in a JSON array. In this case this documentation describes the structure for each object inside of the JSON array. In all other cases the returned response is a JSON object with the described structure.


login

A login method for using the socket connection


Parameters:

Name

Type

Description

username String The username which should be logged in
password String The users password


Return Events:

  • err

    Server response on error containing an error object

    Key

    Type

    Description

    status number Statuscode Number
    message String Error description
    code String Statuscode Text

  • login answer

    Server response on success containing the sockettoken which can be used for authentification within this session

    Key

    Type

    Description

    token String The access token to use with the API




getGPS

Fetches the 5 last public entries for the GPS values from the database


Parameters:

Name

Type

Description

token String The sockettoken received by the client after login


Return Events:

  • err

    Server response on error containing an error object

    Key

    Type

    Description

    status number Statuscode Number
    message String Error description
    code String Statuscode Text

  • getGPS answer

    Server response on success containing an array of objects with the fetched data

    Structure of each object inside the array:

    Key

    Type

    Description

    id number The id of the database entry
    _rev String A id-like String fitting a certain eboard
    deviceType String An id referring to the device type of the board which created the entry
    deviceId String The id of the eboard which created the entry
    timestamp String A timestamp in ISO date format



registerLiveDevice

Registers a live device for a logged in user. From then on whenever the user is online, he will be sent the incoming data from the specified device directly


Parameters:

Name

Type

Description

token String The sockettoken the client received after login
iduser number The id of the device to watch


Return Events:

  • err

    Server response on error containing an error object

    Key

    Type

    Description

    status number Statuscode Number
    message String Error description
    code String Statuscode Text

  • registerLiveDevice answer

    Server response on successful registration containing and approval message behing the 'message' key

    Key

    Type

    Description

    message String A success message containing the user id of the requestor and the eboard



unregisterLiveDevice

Deletes a registration for a certain live device


Parameters:

Name

Type

Description

token String The sockettoken the client received after login
iduser number The id of the device to delete the registration from


Return Events:

  • err

    Server response on error containing an error object

    Key

    Type

    Description

    status number Statuscode Number
    message String Error description
    code String Statuscode Text

  • unregisterLiveDevice answer

    Server response on succsessful deletion of the registration

    Key

    Type

    Description

    message String A success message containing the id of the unregistered device



heartbeat

Test method to check the connection. The client will receive an empty response at the heartbeatResponse if the sent object contains a field 'online' which is truthy


Parameters:

Name

Type

Description

online boolean Should contain 'true' in order to get a result but any truthy value will do


Return Events:

  • heartbeatResponse

    Server response if the online parameter is truthy

    Sends an empty object




getEBoardList

Fetches a list of all available eBoards to register on


Parameters:

Name

Type

Description

token String The scokettoken the client received after login


Return Events:

  • err

    Server response on error containing an error object

    Key

    Type

    Description

    status number Statuscode Number
    message String Error description
    code String Statuscode Text

  • getEBoardList answer

    Server response on success containing an array of objects with eBoard information

    Structure of each object inside the array:

    Key

    Type

    Description

    id number User id of the eBoard
    watching boolean True if this eBoard is already being watched by the current user
    private boolean True if this eBoard is within the same team as the current user