All hosts sharing one database are connected and build a ROAD cluster. To get to know which hosts there are and about their current state, a client can query for them.


About Hosts

All hosts sharing one database are connected and build a ROAD cluster. To get to know which hosts there are and about their current state, a client can query for them.

Each ROAD Service instance updates this information in the database periodically, so clients can assume if they are currently running. The cycle time can be configured for the ROAD Service locally, that's why it is included in the host information.

(warning) For now this interface is read-only. Modifying these information is due to the hosts themselves.

Host Data

A host info contains these data fields:



Host name as used for communication (in lowercase; usually its network name).

Must be unique inside a ROAD cluster.

descriptionDescription or descriptive name to appear for end users (optional field)


Current version of the ROAD Service (e.g. "1.2.339.0")



URL to access this host incl. port. If both http and https are configured, the preferred one is set here (which is https).

Deprecated since v1.2.392.0! Use RestAddress instead.

restAddressHTTP or HTTPS URL to access this host for REST requests.
socketAddressWS or WSS URL to access this host via web socket.


Interval of cyclic updating this information in milliseconds.

If the LastAliveTime + UpdateAliveInterval is distinctly in the past, it might be assumed that this Service instance is no longer running. If IsRunning still is true, it likely was aborted irregularly.


Date+time (ISO format) of last updating this information by the respective ROAD Service instance.


true while Service is active, false after it was finished.
isDisabledDisallow running of ROAD Service on this machine. If set to true the Service will not start.


Set to true in case a Service host is marked as no longer active.

Use Cases

  • Get a list of all active hosts
  • Get a list of all deprecated hosts

Interface Usage

REST philosophy is a bit different from function-centric thinking. So to fulfill best practices, we use resource-centric interfaces:

Success ResultDescription

(see below)

OK = 200
JSON formatted results list

Get data for all existing hosts (completely or specific fields).

<uri>/api/hosts?filter=isDeprecated==false&fields=name, serviceVersion&skip=0&limit=20

Note: If no matching host is found, the result value is not 404 (not found) - instead an empty results list will be returned.

hosts/{name}GET(see below)

OK = 200
JSON formatted result

Get an existing host's data (completely or specific fields).

You can use "localhost" instead of name to get information about the current machine.

Example: <uri>/api/hosts/my-host?fields=name, serviceVersion

Note: If the host is not found, the result value is 404 (not found).

GET: Supported Parameters for categories

Optional Query Parameters (for all GET requests)



Limit the response to specified fieldsfields=name, lastAliveTime


Search filter. See Query Expressions for a detailed description. See above for fields which are supported by this interface.

Note "localhost" can always be used as an alias for the host which processes this request.



Sort order. Comma-separated list of sort fields. An optional "asc" or "desc" can be added after each field name (separated by space).sort=name desc



Offset in results list (default: 0)

offset and skip are synonymic

limitLimit the result list size (default: 100)limit=100

Hosts Data as REST Body

Where hosts data is transferred with a REST request to ROAD Service or response from ROAD Service, it is formatted as a JSON.

Example JSON

    "name": "road-server42",
    "description": "Studio 2",
    "serviceVersion": "1.2.338.0",
    "restAddres": "https://road-server42:11004",
    "socketAddress": "wss://road-server42:11006",
    "updateAliveInterval": 3600000,
    "lastAliveTime": "2021-06-10T09:20:57.159Z",
    "isRunning": true,
    "isDisabled": false,
    "isDeprecated": false