/State/status
/State/allowed
/State/transition
/State/shutdown
/Programs/status
/KVStore/value
/KVStore/listnames
/KVStore/list
/KVSTore/set
/Loggers/enable
/Loggers/disable
/Loggers/list
/Loggers/record
/Loggers/isrecording
/Loggers/start
/Loggers/stop
/Loggers/status
The DAQ Experiment manager daemon provides a REST interface that allows external programs to control and query it. This manpage describes the requests that can be made and the form of the response you can expect. Note that Tcl client bindings already exist and are documented elsewhere. This page documents the URLs, the parameters they require and the returned data.
REST interfaces use standard HTTPD protocols to provide an in interface by which a client can make a server do something other than simply return some HTML to be rendered in a browser. In REST interfaces, the requests are encoded a URLs with parameters provided either as query parameters or as POST parameters.
In the case of the program manager, returned data are JSON encoded objects. All of these objects have at least the atributes status which should be OK on success or ERROR on failure, and message which, in the case status is ERROR, provides a textual message string that describes why the action failed.
REST requests are expressed as URLs. The server provides several categories of REST requests or, as the server technology it uses calls them Domains. These domains are:
Provides control and query of the state machine.
provides status of programs run by the server.
Provides access to the key value store maintained by the server's configuration database.
Provides status and control over event loggers managed by the server.
Specific requests within a domain are encoded within the URL. For example; To obtain the current state of the state machine, you would perform the GET method on a URL of the form: http://serverhost:serverport/State/status. In this URL, serverhost is the host in which the server is running and serverport is the port the server is listening on for HTTP connections. This can be discovered by interacting with the port manager of serverhost to translate the service name given the user that started the manager.
The remaining sections document each domain and the requests it supports. Note that unless otherwise indictated, a request can be made via the GET method. Parameters are either query parameters appended to the URL, in the case of GET request or POST form parameters in the case of POST requests.
This domain provides access to the experiment manager's state machine. Note that in all requests a JSON encoded object is returned (mimetype application/json). We document the attributes in addition to status and message in the case status is OK. The following requests are supported:
Returns a JSON object with the attribute state. The value of this attribute is the textual state name of the current state.
Returns a JSON object with the attribute states. The value of this attributes is an array of strings that are the state names of states the system can be made to transition to.
This request must be issued with a POST method. The required
parameters are:
user the username of the user issuing
the request and state the requested
name of the state to transition to.
In the future user will be used in
conjunction with the authorization database to ensure the
user is authorized to request this transition.
Authentication is 'honesty is the best policy' which is not secure at all but ok in the context of a collaborative experiment.
This request must be issued with a POST method. The required parameter is user, the user name of the person issuing the request.
The server first performsa transtion to SHUTDOWN. Once this transition is complete, the return data, which has no additional attributes is sent to the server and, the program exit is scheduled.
There is some delay between the request and the actual shutdown. This is done to ensure the requester has been sent the reply data before the server is actually shutdown.
The requests in this domain provide information about the programs and containers under the control of the manager. Note that there is only one request: /status. This request requires no parameters and a GET method may be used to initiate it. In addition to the status and message attributes, if status is OK, the reply contains two additional attributes: containers and programs.
The containers attribute is an array of objects. Each object describes a container managed by the server. The program attribute is an array of objects. Each of those objects describes a program managed by the server.
The attributes of each element of the containers attribute are:
The name of the container.
The container image path. This file will be specified by a path in the host system.
An array of host/container filesystem bindings. Each element
is expressed in a form suitable for use with the
singularity --bind option.
That is either hostpath or
hostpath:containerpath.
An array of hostnames in which the container is currently active.
The elements of the programs array are objects that have the following attributes:
The name of the program.
The path to the program file. The meaning of this path depends on the environment in which the program is run. If the program is containerized, this path is specified within the running container's filesystem. If not containerized, this path is expressed in terms of the host system's filesystem.
The textual program type. This is one of Transitory, Critical or Persistent.
The container the program runs in. If the program does not run containerized, this is an empty string.
A boolean value that is true if the program is running or false otherwise. For the purposes of REST interfaces 1 is true and 0 is fales.
The requests in this domain provide access to the key value store through the server. Accessing this information via the server, rather than via direct database transactions, inherently serializes all operations which, otherwise might, due to parallelism, result in unpredictable results. Even so, care must be taken.
The supported requests in this domain are:
Requires the parameter name which must be the name of an existing Key Value store key. On status of OK, the returned object includes the attributes name, which is, once more the name of the key being queried and value its current value.
On status of OK, the reply JSON object contains the attribute names which is an array of strings. Each string is a valid key in the key values store and all keys are present in the array. The user should not assume this array is in any particular order.
On status of OK, the reply JSON includes the attribute variables. The value of this attribute is an array of objects. Each object in the array contains the attributes name which is a key in the key value store and value which is the value associated with that key.
All key value pairs will be represented in the array. You should not assume the array is in any particular order.
This request requires a POST method. Changes the value of a key in the key values store. Required parameters are:
Username of the requester (will eventually be used to check authorization)
Name of the key to modify.
New value to give to the value of that key.
Note that name must be an existing key. This request cannot be used to create a new key. On status of OK, the returned JSON object will have the additional attributes: name, the original key name. value the new value.
Requests in this domain control and get information about the
event loggers that are managed by the server. In the request documentation
below, the returned object attributes are only present if the
status attribute has the value OK.
Note as well that all requests documented as needing to use the
POST method have a required parameter
user which is the name of the user that is
making the request.
Enables a specific logger.
This request must use the POST method. In addition it must supply the logger parameter which specifies the destination of the logger to enable. The returned object does not have any additional attributes.
Disables a specific logger.
This request must use the POST method. In addition in must supply the logger parameter which specifies the destination of the logger to be disabled. The returned object has no additional attributes.
Returns an object that has the addition attributes loggers. The value of this attribute is an array of JSON encoded objects. Each object in the array describes a logger. These object have the following attributes:
Primary key of the logger in the database. For most REST clients this is not useful.
The root of the NSCLDAQ installation tree from which the logger will be run. This indirectly specifies the event logging program that will be used.
If the logger is run containerized, this path will be specified in the filesystem as seen within the running container.
URI of the ringbuffer that will be logged.
Host in which the event logger will be run.
Non zero if this logger is a partial (multilogger style) logger.
Filesystem path to where the data will be logged. If the logger runs containerized, this is expressed in the filesystem as seen by the container.
If this logger is partial, this is the path to the directory in which the data are logged. If not, this path is the top level of the directory tree of the logger directory structure.
If nonzero, premature exits of this logger will result in a forced SHUTDOWN transition.
If non zero the logger is enabled.
Name of the container if the logger should be run containerized. If this is an empty string, the logger is run in the host system.
Sets the state of the global recording flag. This request
must be done as POST method and requires
a POST parameter state which is
an integer. A value of 1 enables recording, zero values
disable it. All other values are illegal and result in an
error object.
On success, no additional attributes are defined in the returned object.
Returns an object with the additional attribute state which is 1 if the global recording flag is set and 0 if not.
POST method required. This request begins the event loggers that are entitled to start for this run. A logger starts if the global recording flag is set and that logger is enabled.
Not yet implemented.
Not yet implemented.