api/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.

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.

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:

Field	Description
name	Host name as used for communication (in lowercase; usually its network name). Must be unique inside a ROAD cluster.
description	Description or descriptive name to appear for end users (optional field)
serviceVersion	Current version of the ROAD Service (e.g. "1.2.339.0")
url (deprecated)	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.
restAddress	HTTP or HTTPS URL to access this host for REST requests.
socketAddress	WS or WSS URL to access this host via web socket.
updateAliveInterval	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.
lastAliveTime	Date+time (ISO format) of last updating this information by the respective ROAD Service instance.
isRunning	true while Service is active, false after it was finished.
isDisabled	Disallow running of ROAD Service on this machine. If set to true the Service will not start.
isDeprecated	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:

URI

Verb

Parameters
(optional)

Success Result

Description

hosts

GET

(see below)

OK = 200
JSON formatted results list

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

Examples:
<uri>/api/hosts
<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)

Parameter	Description	Example
fields	Limit the response to specified fields	fields=name, lastAliveTime
filter	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.	filter=name==localhost
sort	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 skip	Offset in results list (default: 0) offset and skip are synonymic	offset=100
limit	Limit 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
}

JS

Contents