Update

Real time updates are very important to ensure that the data in the application is always up-to-date. For the Java clients there are two options available to receive updates:

• pulling at a configured intervall, or
• via the WebSocket connection

The prefered update method is the WebSocket. It is significantly more effecient than requesting updates via the Rest-API. For features like the execution response, a WebSocket connection is even required.

WebSocket

The technical aspect of the WebSocket connection is described below so that you can also use it in other applications.

To establish a connection, you have to send an HTTP request to wss://rpdb.rpjosh.de/api/socket. The header of the request may contain the following fields.

Name	Type	Description
Client-Version	string	Current version of the client. Some features require an up-to date client → provide downward compatibility
Client-Date	DateTime	The current date and time of the client. This is used to determine an offset that is automatically applied for all returned entries. Defaulting to the users' timezone
X-Api-Key	string	API-Key to authenticate against the server
Version	int	The last version number the client is aware of. All updates since this version are returned after the handshake
Version-Date	DateTime	If the version number of the data is not known by the client, you can also pass the date of the last fetch. The current version and all updates since this version are returned after the handshake
Username + Password	string	Instead of using an API-Key to authenticate, you can also pass a username and password directly (not recommended)

After performing the handshake and the HTTP upgrade, you are successfully connected to the socket server. The server will immediately send an update message for the given Version and Version-Date.

Info

To check if a client is still connected, the server sends a Ping / Pong request every 10 minutes. This timeout should also be used by the client to detect if the server is gone away - which shouldn't happen often :)

Messages from server to client

There are three different types of messages, that can be sent from the socket server.

Update

The most used message types are updates. It contains all deleted, updated and created attributes and entries, as well as the current version details.

{
   "type":"update",
   "update":{
      "version":1209,
      "version_date":"2023-04-09T10:00:59",
      "entry":{
         "deleted":[ 2001 ],
         "updated":[
            {
               "id":2340,
               "attribute":{
                  "id":1
               },
               "date_time":"2026-04-07T20:20:00",
               "date_time_execution":"2026-04-07T20:20:00",
               "creator":64,
               "parameters": [
                   {
                      "parameter_id": 568,
                      "value": "Send a mail",
                      "preset": null
                   }
                ]
            }
         ],
         "created":[ ]
      },
      "attribute":{
         "deleted":[ ],
         "updated":[ ],
         "created":[
            {
                  "id":2,
                  "name":"My-name",
                  "execute_always":false,
                  "no_db":false,
                  "exec_response":false,
                  "force_parameter":false,
                  "parameter":[],
                  "rights":"all"
            }
         ]
      }
   }
}

Execution response and NoDB

For attributes of the type no_db and execution response, an own message type has been declared to avoid misunderstandings.

{
   "type":"exec_response",
   "exec_response":{
      "id":-8749052605,
      "attribute":{
         "id":5
      },
      "date_time":"2023-04-09T08:04:47",
      "date_time_execution":"2023-04-09T08:04:47"
      "parameters": [
        {
            "parameter_id": 567,
            "value": "Send a mail",
            "preset": null
        }
      ]
   }
}

---

{
   "type":"no_db",
   "no_db":[
      {
         "id":-4222555566,
         "attribute":{
            "id":6
         },
         "date_time":"2023-04-10T18:09:34",
         "date_time_execution":"2023-04-10T18:09:34",
         "parameters": [
            {
               "parameter_id": 568,
               "value": "Send a mail",
               "preset": null
            }
         ]
      }
   ]
}

Messages from client to server

The only message the client may send to the server is the execution response. It contains the exit code and the output of the program.

"exec_response": {
    "entry_id": -17541,

    "response_code": 0,
    "response": "This is the stdout from the executed script"
}