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 ],
"deletedPre": [
{
"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
}
]
}
],
"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"
}