The TINE client RESTful (Representational State Transfer) is described below. The web address for TINE RESTful services follows the schematic

host-url:8080/TINE_Restful/

where the user can submit a request for information (lists of available contexts, servers, devices, etc.) or a request for the current readback values of control system elements as well as their archived values.

The user can also submit a request to change the control system element settings and set points.

Queries for Readback Information

The readback results from a control system element can be obtained by providing the control system address immediately after the URL to the web server hosting the TINE_Restful servlet. If the request is simple http (i.e. from a browser) and a content is not given in the request, plain text will be returned. That is, a request of the form:

(url)/TINE_Restful/Context/Server/Device/Property/? will return the results as a text string of the form timestamp : data values.

In the above example, the entire X-Orbit is returned, as no requested data size (or format) was specified.

Additional data request parameters can be specified following the query '?'.

Syntax: (url)/TINE_Restful/Context/Server/Device/Property/?&size=SIZE&format=TYPE&input=INPUT&access=ACCESS One can request a setting change by making use of the input and access parameters (i.e. input = the desired setting, and access = WRITE).

\nFor instance

The above request issued a set (due to the input data value and the WRITE access) and requested an atomic readback (a RW operation, if you will) of the same property value (size = 1).

If the request itself comes in as a JSON or XML request, then the returned content will also be of JSON or XML format. Otherwise, one can request a specific content by supplying the &content=\emCONTENT parameter in the request, where CONTENT can be JSON :

or XML :

Usually, one can safely omit the format parameter, as the TINE RESTful engine will attempt to determine the optimal data format, which is especially useful when dealing with structures. If a structure is returned the value string returned will identify it as a structure and clearly identify the embedded fields.

For example:

In general, requests for readback data from an address will result in an asynchonous listener being instantiated at the web server (if necessary) and any returned results come from the listener. This strategy yields a very efficient web servlet, capable of supporting many simultaneus clients, without the need of extra load balancing. WRITE access calls and information queries (see below) are, on the other hand, execulted synchronously. If a readback request for some address is not repeated with a timeframe of 5 minutes, the listener is stopped and removed from the listener table.

The current activity at the servlet end can be examined by sending an explicit query for stats. For example :

Queries for Archive Information

Trends of control system elements (for those elements configured to keep histories) can easily be obtained by supplying the trend parameter in the RESTful request. In this case the trend parameter should give the desired trend depth. If no units are specified, then seconds are assumed. Otherwise, the trend parameter setting should be of the form &trend=24HOURS, 7DAYS, 60MINUTES, 5000MSECS, etc. If the stop time is unspecified then now is assumed. One can supply the stop time with the time parameter in the form of &em time=now or &time= dd.mm.yyyy hh:mm:ss

For example:

Note that the returned data is of the form of an array of value-UTC timestamp doublets.

In addition, a snapshot of a control system element which delivers an array can be obtained. For such requests, the trend parameter should explicitly be set to snapshot. The time parameter should then be set the desired target time.

For example:

Note that if the returned array refers to a multi-channel array (as in the example above) then it is the user's responsibility to know the channel names of the array entries. If the returned array refers to a trace (or waveform) it is likewise the user's responsibility to know the increment between the array elements.

Queries for List Information

One can query for lists in basically the same manner as per readback values, by simply omitting the targeted list type in the given address. For instance, by not specifying a Server in the URL target request, a list of all servers relevant to the given context will be returned.

Omitting the Device in the target request will return a list of all devices supported by the given Server (and Property if also given):

And omitting the Property in the target request will return a list of all properties supported by the given Server and Device:

Note that the central archive server (Server = HISTORY) can be supplied as well as a specific control system server. In the former case, the requested property should be a centrally archived keyword. In the later, the requested property should be configured to have a local history, otherwise an error will be returned.

Queries for Alarms

Analogous to a request for archive data, one can also request alarm information. Here the trend and time parameters have the same meaning as for an archive request, namely specifying a time range for the desired alarms.

To request alarms, one needs only to request the property ALARMS. For example:

The request can be made to the central alarm server (Server=CAS) or to a specific control system server.

Queries for Commands

One can obtain useful information from a target address as to its recent commands log. Such information is often of use when it is important to know what settings were changed when and from what source.

For a recent Commands list the request is made as if it were a simple request for readback data but with the Property parameter equal to COMMANDS. For example :