With the help of the Cordaware API interface, you have a so-called REST API at your disposal.
All requests are sent to the REST API via an HTTP POST request to the address of your Infoserver with the path “/rest”. For example, if your Infoserver is accessible via “bestinformed.local” and uses the standard port 8431 for the TLS secured connection, the address of the REST API is:
|
https://bestinformed.local:8431/rest |
Athentication on the server
in order to use the API interface, athentication is necessary. This is done with the help of a secret which is stored in a password vault.
To create a password vault, open the Password app and click on the green "+" icon to create a new vault.
Now enter a name, an optional description and a password for your vault.
|
Please note that the name of the password vault needs to begin with "rest_"! |
The password hash needs to be send in the HTTP Header "X-Best-Auth".
The algorithm in pseudocode calculates this header as follows:
|
Salt = random_string() |
The content of the "XBestAuth" variable can now be inserted in the header.
|
Please note: For security reasons a salt should only be used once and be generated anew for each request |
If the credentials sent to the servers are incorrect, the connection is closed without sending a reply. (ECONNCLOSED)
Request to the API interface
The actual request to the REST API is sent in the body of the POST request. This must be an UTF8 encoded JSON string that contains the key "action". This specifies what action the API should take. Depending on the selected action, additional information and optional keys may be added.
|
Please note that the origin header must be admitted in your request. The origin header must contain the address of the website or server used, from which the REST API is addressed. These must also be stored in the system settings via System -> System (Global)
 |
Examples
The following is a list of all available actions, their keys and an example of this request.
Action: running
Puts out a list of all currently active Infos and their details.
Example request:
{ "action": "running" } |
Note:
This action will not view the canceled Infos. Canceled Infos can be recognized by the fact that those contain the "canceled" key with a time stamp when it was canceled.
Other usable keys:
•"skip" (integer) - Skips the first N results. (optional)
•"limit" (integer) - Limits the number of results to a maximum of N. (optional)
•"begin" (date) - Only Infos from this time on will be displayed. (optional)
•"end" (date) - Only Infos before this time will be displayed. (optional)
•"month" (integer) - Only Infos from this month will be displayed. (optional)
•"year" (integer) - Only Infos from this year will be displayed. (optional)
•"canceled" (boolean) - Only canceled Infos are displayed. (optional)
•"includerecipient" (boolean) - The response also includes the amount of Sent (_sent), Answers (_response) and Recipients (_received) for each Info. (optional)
Example response of the API:
{ "type": "running", "count": 1, "result": [ { "_id": "bi-info_05affc0d82f97dbbaaebf45420674173", "timestamp": "2020-09-23T14:39:36Z", "end": "2020-09-23T14:42:36Z", "begin": "2020-09-23T14:39:36Z", "minutes": 5, "active": 3, "doc_user": "admin", "info_0": "Exchange Server unavailable today from 13:00!" // ... & many more keys shortened } ] } |
Action: all
Outputs a list of all Infos and their details.
Example request:
{ "action": "all" } |
Other usable keys:
•"skip" (integer) - Skips the first N results. (optional)
•"limit" (integer) - Limits the number of results to a maximum of N. (optional)
•"begin" (date) - Only Infos from this time on will be displayed. (optional)
•"end" (date) - Only Infos before this time will be displayed. (optional)
•"month" (integer) - Only Infos from this month will be displayed. (optional)
•"year" (integer) - Only Infos from this year will be displayed. (optional)
•"includerecipient" (boolean) - The response also includes the amount of Sent (_sent), Answers (_response) and Recipients (_received) for each Info. (optional)
Action: history
Outputs a list of all Infos from the Info history and their details.
Example request:
{ "action": "history" } |
Other usable keys:
•"skip" (integer) - Skips the first N results. (optional)
•"limit" (integer) - Limits the number of results to a maximum of N. (optional)
•"begin" (date) - Only Infos from this time on will be displayed. (optional)
•"end" (date) - Only Infos before this time will be displayed. (optional)
•"month" (integer) - Only Infos from this month will be displayed. (optional)
•"year" (integer) - Only Infos from this year will be displayed. (optional)
•"includerecipient" (boolean) - The response also includes the amount of Sent (_sent), Answers (_response) and Recipients (_received) for each Info. (optional)
Action: received
Checks all recipients of a specific Info. Also includes the Infoclients that received the Info and confirmed the receipt.
Example request:
{ "action": "received", "myid": "bi-info_05affc7e3052da74c37b98e31eb83fc9" "limit": 1 } |
Note:
If the addressed Info does not exist, an empty list is returned.
Other usable keys:
•"myid" (string) - The ID of the Info whose recipient should be read out. (required!)
•"skip" (integer) - Skip the first N results. (optional)
•"limit" (integer) - Limits the number of results to a maximum of N. (optional)
•"countonly" (boolean) - "True" returns only the count without results. (optional)
Example response of the API:
{ "type": "receive", "count": 1, "result": [ { "version": "6.3.1.2", "username": "john.doe", "computername": "CW-TEST-427", "guid": "CW-TEST-427-D3-C5-1D-05-7A-3F-77-A3-1", "domain": "cordawaretest", "connected": "2020-09-23T09:47:53Z", "ssl": true, // ... & many more keys shortened } ] } |
Action: sent
Checks all Infoclients to which the Infoserver has sent a certain info, regardless of whether or not the Infoclient has received the Info. (The latter can be carried out with the help of the "received" action)
Example request:
{ "action": "sent", "myid": "bi-info_05affc90dfb0b5bca5b95223a1b207db" } |
Note:
If the Info, whose recipients should be read do not exist, an empty list is returned.
Other usable keys:
•"myid" (string) - The ID of the Info whose recipient should be read out. (required!)
•"skip" (integer) - Skip the first N results. (optional)
•"limit" (integer) - Limits the number of results to a maximum of N. (optional)
•"countonly" (boolean) - "True" returns only the count without results. (optional)
Example response of the API:
{ "type": "sent", "count": 1, "result": [ { "version": "6.3.1.2", "username": "jane.doe", "computername": "CW-TEST-659", "guid": "CW-TEST-659-D3-C5-1D-05-7A-3F-77-A3-1", "domain": "cordawaretest", "connected": "2020-09-23T09:47:53Z", "ssl": true, // ... & many more keys shortened } ] } |
Action: response
Checks the responses to a specific Info.
Example request:
{ "action": "response", "myid": "bi-info_05affcab0c041377482976012ff9eda2" } |
Note:
Unlike other actions, all keys in the answer are capitalized (except "date").
Other usable keys:
•"myid" (string) - The ID of the Info whose recipient should be read out. (required!)
•"skip" (integer) - Skip the first N results. (optional)
•"limit" (integer) - Limits the number of results to a maximum of N. (optional)
•"countonly" (boolean) - "True" returns only the count without results. (optional)
Example response of the API:
{ "type": "response", "count": 2, "result": [ { "date": "2020-09-23T15:24:18Z", "computername": "CW-TEST-421", "username": "jane.doe", "domain": "cordawaretest", "response": "Understood. Thanks for the information.", "os": "Windows" }, { "date": "2020-09-23T15:24:18Z", "computername": "CW-TEST-842", "username": "john.doe", "domain": "cordawaretest", "response": "When will the server be available again?", "os": "Windows" } ] } |
Action: info
Checks all the details of a specific Info.
Example request:
{ "action": "info", "myid": "bi-info_05b001f0231e517b5c2ab73d4387c796" } |
Other usable keys:
•"myid" (string) - The ID of the Info whose recipients should be read. (required!)
Example response from the API:
{ "type": "info", "count": 1, "result": { "_id": "bi-info_05b001f0231e517b5c2ab73d4387c796", "end": "2020-09-24T09:55:46Z", "begin": "2020-09-24T09:55:46Z", "doc_editor": "", "minutes": 5, "showonuserdesktop": true, "doc_roles": [], "profile_id": "root", "active": 3, "cancloseonuserdesktop": true, "closeonclick": true, "cancloseonwinlogondesktop": true, "cancelonclose": true, "info_0": "The cleaners are coming an hour earlier than usual today due to the company party." // ... & many more keys shortened } } |
Action: newinfo
With the help of the newinfo action, new Infos can be created
Example request:
{ "action": "newinfo", "info": "Hello World from the REST API!", "minutes": "5", "active": "3" } |
Other usable keys:
•"isinifile" - This allows you to set your Info to configure the recipient's Infoclient.ini.
•"isinifiletext" - This allows you to specify the Infoclient.ini settings to be adjusted.
|
Hint:
When creating Infos, you can already create and design the Info on the Cordaware bestinformed web interface. You can then view a REST API view using the JSON->REST button.
You can now copy the contents of the API view and use it in your API request. |
Set the start and end of the info.
If you want to define the start and end of the info, use the keywords “begin” and “end”. Here is an example.
{ |
*this info starts on 01.01.2025 at 7 am and ends on 01.01.2025 at 3:30 pm (UTC), for the actual display time please consider your time zone.
Action: editinfo
This action allows you to edit Infos
Example request:
{ "action": "editinfo", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9", "info": "Info was edited using the REST API!" } |
Other usable keys:
•"myid" (string) - The ID of the Info whose recipients should be read out. (required!) - Note here that the Info-ID does not include the beginning "bi-info_"!
Action: cancelinfo
This allows you to cancel Infos.
Example request:
{ "action": "cancelinfo", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9" } |
Other usable keys:
•"myid" (string) - The ID of the Info whose recipient should be read out. (required!)
Action: deleteinfo
This allows you to delete Infos.
Note:
Deleted Infos, which are still active with an user, will continue to be displayed on their screens! Deleting the Info does not cancel it on the screens.
Example request:
{ "action": "deleteinfo", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9" } |
Other usable keys:
•"myid" (string) - The ID of the Info whose recipient should be read out. (required!)
Action: copycancel
This can be used to send the all-clear of Infos.
Note:
The all-clear of an Info can only be sent if a corresponding all-clear Infotext was also provided when the Info was created.
Example request:
{ "action": "copycancel", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9" } |
Other usable keys:
• "myid" (string) - The ID of the info whose recipients should be read. (Required!)