Interface description

All Modelverse components communicate with each other through the use of sockets. On these sockets, XML/HTTP Requests are used for communication. In this brief section, we describe the form of these requests.

MvS server

The MvS server listens to a fixed set of commands. All commands have a fully defined signature and result. Note that commands are encoded: a decoding table is presented below.

Code Description
CN create_node
CE create_edge
CNV create_nodevalue
CD create_dict
RV read_value
RO read_outgoing
RI read_incoming
RE read_edge
RD read_dict
RDN read_dict_node
RDNE read_dict_node_edge
RDE read_dict_edge
RRD read_reverse_dict
RR read_root
RDK read_dict_keys
DE delete_edge
DN delete_node

Requests are sent as POST requests (i.e., in the data of a HTTP request). They have the following form:

op=CODE&params=PARAMS

In this case, CODE is one of the codes mentioned above, and the value of PARAMS is a JSON encoded list of Modelverse identifiers. The choice of what is a Modelverse identifier is left to the MvS itself.

The result will be a JSON serialized list containing as first element the response to the request, and as second element the statuscode. If the statuscode is 200, the first element will be correct. Otherwise, the statuscode indicates the error, and the first element is set to null.

MvK server

The communication with the MvK is a lot easier, as there is only a very minimal interface: the actual interface needs to be explicitly modelled in action language. Requests have the following form:

op=OPERATION&taskname=TASKNAME&value=VALUE

Here, OPERATION defines the operation to execute, of which only two exist:

  1. set_input, which adds the sent value to the input queue of the user;
  2. get_output, which blocks until there is a value in the output queue of the user.

Obviously, TASKNAME specifies the name of the task for which the operation needs to happen.

The VALUE is just a JSON encoded value which will be added to the input queue of the Modelverse. This is ignored when the get_output operation is used. Note that there are some minor differences between our encoding and JSON encoding.

The supported types are shown below.

Type Example
Integer 1
Float 1.0
Boolean true
String “abc”
Action if

While this list mostly resembles JSON, there are some important differences:

  • Lists and objects are not supported;
  • Null object is not supported;
  • Action type is new, and contains a string representation (without quotes!) of the action language construct to add

As response, the set_input will always receive the same reply if the message was correctly deserialized. Receiving a reply does NOT mean that a message was consumed by the task, it only means that the message was correctly added to the input queue of that task.

A get_output request blocks until a value is available in the tasks output queue. The reply to this message will then contain a JSON serialized (with identical remarks as for set_input) containing the value that was output. Note that now the null message is possible, in case the node that is being outputted does not contain a value (or is an edge).

Performance notes

For performance reasons, sending a huge amount of data to the Modelverse (e.g., a compiled program), should not happen with individual requests for each line. To allow for packed messages, tasks can ignore the value parameter, and use the data parameter instead. The content of this parameter should be a JSON encoded list of all individual values to be inserted.