JSON API

The JSON API contained within the Web Utility. It allows for automated control of the entire test platform. The JSON API is implemented via a HTTP servlet as well as via a Web Socket connection. There are advantages and disadvantages of both.

Servlet

The JSON API provided via the servlet is a simple request-response API. It does not provide an event driven API. However, the Servlet JSON API may still be used to query the entire state of a JDNP3 instance.

The JSON servlet is accessed via http://<your_host>/servlet/jsonapi

Web Socket

The Web Socket API can be used to perform all the tasks that the Servlet API can perform. The key advantage with the Web Socket API is that it support real-time update notifications from the server. During establishment, the Web Socket API is configured to either listen to events from a particular outstation or for general configuration events.

The Web Socket API is accessed via http://<your_host>/ws/device[?site=<site>&device=<device>]
The optional site and device parameters identify an outstation. If supplied, they register the Web Socket to events on the specified outstation. You may register to a non-existant outstation and events will begin when the outstation is created.

Note: There is also Station Web Socket API. This is deprecated.

Which should I use?

The advantage of using the Servlet API is that it supports events. However, the Servlet API is just a simple HTTP POST. It is more likely that your chosen framework will guide your decision.

Requests

Requests are messages sent from the client to the server. Regardless of the mechanism used, requests always have the same format.

{
    'type': <message type>,
    <other data>
}

Responses

Responses are messages sent from the server to the client. They may be unsolicit if the response is a notification of an event. Regardless of the mechanism used, responses always have the same formet. Event if a response is expected in relation to an event, they should be considered asynchronous.

{
    'type': <message type>,
    <other data>
}

JSON Messages

List Devices

Request

{
    'type': 'listDevices'
}

Response

{
    'type': 'siteList',
    'siteDeviceList': [
        {
            'site': <site name>,
            'devices': [<device 1>, <device 2>, ...]
        },
        ...
    ]
}