3.4 HTTP API
A client drives the runtime over HTTP: it creates environments, uploads models, runs them, registers WebSocket clients and talks to features. The examples use the lamp of the IDE example examples/lamp and the runtime at http://127.0.0.1:8080.
3.4.1 Conventions#
Parameters go in the query string. Uploads and messages to features go in the body as plain text. The runtime accepts requests from any origin.
A successful call answers status 200. Its body is empty unless the route below names an answer. A failed call answers one of these statuses with the reason as plain text in the body:
| Status | When |
|---|---|
| 400 | A parameter is missing or wrong, the environment does not exist, a name is unknown, or an upload has errors |
| 409 | The call does not fit the phase of the environment or what it holds |
| 500 | Anything else went wrong |
A missing parameter gives the text Missing required parameter: <name>, an unknown environment Environment with key <envKey> does not exist.
| Group | Routes |
|---|---|
| 3.4.2 Environments | POST /createEnvironment, POST /dropEnvironment |
| 3.4.3 Uploads | PUT /setMetamodel, PUT /setModel, PUT /setEventDefinitions, PUT /setStateMachine |
| 3.4.5 Settings | POST /setTickDelay, POST /setEventTtl |
| 3.4.6 Clients | POST /registerClientForWebSocket, POST /registerObjectObserver, POST /registerDomainListener |
| 3.4.7 Running | POST /runEnvironment, POST /startEnvironment, POST /stopEnvironment, POST /setActiveState |
| 3.4.8 Observation | GET /observatory/environments, GET /observatory/statemachine, GET /observatory/stateMachines, POST /observatory/registerClient, GET /observatory/model, POST /observatory/subscribeModel, POST /observatory/unsubscribeModel |
| 3.4.9 Health | GET /health |
| 3.4.10 Features | GET /getRegisteredFeatures, GET /getActiveFeatures, POST /activateFeature, POST /deactivateFeature, POST /sendMessageToFeature |
3.4.2 Environments#
POST /createEnvironment creates an environment in the phase configuring and answers its key as text. The key has the form env-<milliseconds since 1970> and is never handed out twice by one runtime.
curl -X POST "http://127.0.0.1:8080/createEnvironment"
env-1763035112345
POST /dropEnvironment with envKey drops the environment for good, in every phase: configuring, activated, running, halted and stopped. The runtime ends everything the environment owns: the engine with its thread and the threads of branches, a pause of TickByTick or a halt at a breakpoint, the Python sessions, the features with what they recorded, the events that wait, the observers and listeners, the access keys that no client used yet, and the WebSocket connections of its clients, which close with code 1000 and the reason Environment dropped. The trace log is closed and stays on disk. Pushes that the runtime has not sent yet when the drop comes are not sent any more, so a client that needs the last model reads the snapshot of 3.4.8 Observation before it drops.
The call answers 200 with an empty body once the engine has ended, normally within the rest of the running tick. A tick that does not end within 5 s, because an EVAL waits for Python, has its Python processes ended and its thread interrupted; the call answers after that. A drop that comes while a stop or a start is under way waits for it. From the moment the drop begins, every route answers for the key as for an environment that never existed, the key no longer appears in observatory/environments, and the runtime never hands it out again. So of two drops of one environment at the same time, one answers 200 and the other 400 with Environment with key <envKey> does not exist, which is also the answer for a key that never existed.
curl -X POST "http://127.0.0.1:8080/dropEnvironment?envKey=env-1763035112345"
3.4.3 Uploads#
The four upload routes take the text of a file as body and the key of the environment as envKey. They work only in the phase configuring; after runEnvironment they answer 409 with Environment with key <envKey> is already active and cannot be modified in the intended way. The runtime reads every upload at once. A text with errors is refused, as 3.4.4 Rejected uploads describes, and the environment stays as it was. A byte order mark at the very start of a text is ignored, so such a text is read like the same text without it. An accepted upload replaces the one before it. Warnings of the readers do not refuse an upload; the runtime prints them on its console.
| Route | Parameters | Body |
|---|---|---|
PUT /setMetamodel | envKey | A KMeta text |
PUT /setModel | envKey | A KModel text |
PUT /setEventDefinitions | envKey | A KMeta text with the event definitions |
PUT /setStateMachine | envKey, attachedTo for an attached state machine | A KStates text, also a fragment |
setModel reads the model against the metamodel of the environment and answers 409 with Metamodel must be set before receiving a model for environment <envKey> when there is none. A new metamodel after the model does not read the model again.
setEventDefinitions reads the event definitions with the types of the metamodel at hand, so an event type may use the types of the domain. Upload the metamodel first when it does. The event definitions are 2.1 KMeta types, one per event, named like the event.
setStateMachine takes the two forms of 2.3.11 State machine management and lifecycle. With attachedTo, the text must be an attached state machine, STATEMACHINE ATTACHED TO "Type", and the runtime attaches it to the object of the model whose key is attachedTo. One object has at most one attached state machine; a second upload for the same key replaces it and keeps its place in the order of the state machines. The runtime does not compare the type in ATTACHED TO with the type of the object.
Without attachedTo, the text must be an attachable state machine, STATEMACHINE "name" ATTACHABLE TO "Type", ..., and the runtime keeps it as a definition under its name. Objects get instances of it at run time, as 3.1.13 State machine management and lifecycle describes. A second upload with the same name replaces it and keeps its place. An environment holds any number of definitions besides its attached state machines.
Without attachedTo, the text may also be a fragment, STATEMACHINE "name" FRAGMENT, of 2.3.12 Pages. The runtime keeps it under its name, and the container states of the other state machines use it, as 3.1.14 Pages describes. A fragment is never attached to an object. Upload every fragment that a state machine of the environment uses, directly or through other fragments, before runEnvironment. Attachable state machines and fragments share one name space: an upload replaces the one of the same name, whichever form it had. Of the same form it keeps the place of the old one; of the other form the old one leaves and the new one comes at the end of its kind. observatory/statemachine answers the text of a fragment by its name; the route observatory/stateMachines does not list fragments. An empty name in the header of a fragment or an attachable state machine, STATEMACHINE "" FRAGMENT, and an empty name after USE are errors of the reader, so such a text is refused as 3.4.4 Rejected uploads describes.
The runtime reads the text with all optional features of the language switched on. A text in the wrong form answers 400 with one of these texts, and the environment stays as it was:
-
The state machine for '<attachedTo>' must have the attached form STATEMACHINE ATTACHED TO "Type", but it is the attachable state machine '<name>'; upload an attachable state machine without attachedTo -
The state machine for '<attachedTo>' must have the attached form STATEMACHINE ATTACHED TO "Type", but it is the fragment '<name>'; upload a fragment without attachedTo -
A state machine without attachedTo must have the attachable form STATEMACHINE "name" ATTACHABLE TO "Type" or the fragment form STATEMACHINE "name" FRAGMENT; give attachedTo for a state machine ATTACHED TO a type
curl -X PUT "http://127.0.0.1:8080/setMetamodel?envKey=env-1763035112345" --data-binary @lamp.kmeta
curl -X PUT "http://127.0.0.1:8080/setModel?envKey=env-1763035112345" --data-binary @lamp.kmodel
curl -X PUT "http://127.0.0.1:8080/setEventDefinitions?envKey=env-1763035112345" --data-binary @lamp-events.kmeta
curl -X PUT "http://127.0.0.1:8080/setStateMachine?envKey=env-1763035112345&attachedTo=lamp" --data-binary @lamp.kstates
curl -X PUT "http://127.0.0.1:8080/setStateMachine?envKey=env-1763035112345&attachedTo=wallSwitch" --data-binary @switch.kstates
curl -X PUT "http://127.0.0.1:8080/setStateMachine?envKey=env-1763035112345" --data-binary @glowing.kstates
curl -X PUT "http://127.0.0.1:8080/setStateMachine?envKey=env-1763035112345" --data-binary @bulb-test.frag.kstates
Use --data-binary; -d drops the line breaks, and the lines of errors would no longer fit the file.
3.4.4 Rejected uploads#
An upload with errors answers 400. The body has a first line that names the upload and the number of errors, and one line per error with line, column, message and code, separated by line feeds, without a line feed at the end:
Upload of the <upload> rejected: <n> errors
<line>:<column>: <message> (<code>)
<upload> is metamodel, model, event definitions, state machine for '<attachedTo>' or, for an upload without attachedTo, fragment when the text reads as a fragment and attachable state machine otherwise. For one error the first line ends in 1 error. The codes and messages are the checks of 2.4 Checks.
A metamodel with an unknown property type and a relation to a missing type:
type "Bulb" "A light bulb" {
prop("watts", "decimal")
}
type "Lamp" "A lamp" {
has("bulb", "Bulb")
knows("control", "Switch")
}
Upload of the metamodel rejected: 2 errors
2:20: Unknown type 'decimal' of prop 'watts'; a prop is of type 'string', 'number', 'boolean' (kmeta.unknown-property-type)
6:23: Unknown class type 'Switch' of knows 'control' in type 'Lamp' (kmeta.unknown-target-type)
A model against the lamp metamodel with a wrong number and an unknown property:
make object "lamp":"Lamp" {
prop("mode") -> "off"
has("bulb") -> make object "bulb":"Bulb" {
prop("watts") -> "bright"
prop("colour") -> "white"
}
}
Upload of the model rejected: 2 errors
4:27: 'bright' is not a number, but prop 'watts' is of type 'number' (kmodel.invalid-number)
5:15: Class type 'Bulb' has no property 'colour' (object 'bulb') (kmodel.unknown-property)
A state machine with a transition to a state that does not exist:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "on" { }
}
TRANSITIONS {
TRANSITION "off" -> "on" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "on" -> "dark" {
CONDITION { EVENT("switch", "press") }
}
}
}
Upload of the state machine for 'lamp' rejected: 1 error
10:29: No state is named 'dark'; check the spelling or define the state (kstates.unknown-state)
3.4.5 Settings#
Both settings work only in the phase configuring and answer 409 like the uploads after it.
| Route | Parameters | What it sets |
|---|---|---|
POST /setTickDelay | envKey, milliseconds | The tick delay, the least time from the start of one tick to the start of the next |
POST /setEventTtl | envKey, ttlMs | The time to live of events in milliseconds; 0 means events never expire |
A value that is no whole number gives 400 with Missing or invalid required parameter: milliseconds or Missing or invalid required parameter: ttlMs. Without these calls the environment uses engine.defaultTickDelayMs and engine.defaultEventTtlMs of 3.3.4 Configuration.
curl -X POST "http://127.0.0.1:8080/setTickDelay?envKey=env-1763035112345&milliseconds=500"
curl -X POST "http://127.0.0.1:8080/setEventTtl?envKey=env-1763035112345&ttlMs=5000"
3.4.6 Clients#
POST /registerClientForWebSocket with clientId and envKey registers a client for the WebSocket of the environment and answers an access key as text, in the form ak-<clientId>-<milliseconds>-<number>. The client sends it when it connects, as 3.5 WebSocket describes. An access key works for one connection. The route works in every phase. The client id is chosen by the client.
POST /registerObjectObserver with envKey, clientId and objectId lets the client get the message objectChanged when the object with this key changes and objectDeleted when it is removed. POST /registerDomainListener with envKey, clientId and domain lets the client get the message domainEvent for every event of this domain. Both work only in the phase configuring and answer 409 after it.
curl -X POST "http://127.0.0.1:8080/registerClientForWebSocket?clientId=panel&envKey=env-1763035112345"
curl -X POST "http://127.0.0.1:8080/registerObjectObserver?envKey=env-1763035112345&clientId=panel&objectId=bulb"
curl -X POST "http://127.0.0.1:8080/registerDomainListener?envKey=env-1763035112345&clientId=panel&domain=switch"
ak-panel-1763035113001-4821
3.4.7 Running#
POST /runEnvironment with envKey fixes the configuration and makes the environment ready to start. The phase becomes activated. The call answers 409 with
-
Environment with key <envKey> must have both a metamodel and a model before it can be runwithout metamodel or model, -
Environment with key <envKey> has state machines attached to objects missing from its model: <keys>with the keys separated by,, when a state machine is attached to a key that no object of the model has, -
Environment with key <envKey> has types that behave after state machines it does not hold: <list>when a type of the metamodel behaves after a name that no attachable state machine of the environment has; each entry of the list reads'Bulb' behaves after 'glowing', separated by,, -
Environment with key <envKey> has types that behave after state machines not attachable to them: <list>when the attachable state machine does not list the type; each entry reads'Bulb' behaves after 'glowing', which is attachable to 'Lamp', separated by;, -
Environment with key <envKey> has state machines that cannot be flattened:followed by one line per problem, when a state machine does not flatten with the fragments of the environment, as 3.1.14.1 Flattening at activation describes, -
Environment with key <envKey> is already active and cannot be modified in the intended way.when it ran before.
Each line of a failed flattening names the state machine of the environment, State machine for '<attachedTo>' or Attachable state machine '<name>', then a colon and the problem as 2.3.12 Pages words it. The lines are separated by line feeds, without one at the end. A lamp whose container state uses a fragment that was not uploaded:
Environment with key env-1763035112345 has state machines that cannot be flattened:
State machine for 'lamp': Container state 'self test' of the state machine attached to 'Lamp' uses 'bulb test', but no fragment is named 'bulb test'
The problems are a container state that uses a name no fragment has, or an attachable state machine instead of a fragment, a fragment that contains itself, a qualified name equal to another state name, two different macros of one name, a macro call that no file of the composition defines, and a macro call whose arguments do not fit the macro that another file of the composition defines. The last one reads, for a lamp that calls half of its fragment with two arguments:
State machine for 'lamp': In the state machine attached to 'Lamp': Macro 'half' takes 1 argument, but the call passes 2; pass one argument per TAKES
The environment stays configurable: upload what is missing and call runEnvironment again.
An environment without state machines can run; it only ticks.
POST /startEnvironment with envKey starts the ticks. The phase becomes running. Starting a running environment changes nothing and answers 200. Starting a stopped environment continues the frozen run with the next tick, as 3.1.13.9 Stop and start, forcing and clients describes, and tells every connected client with engineStatus and the phase running.
POST /stopEnvironment with envKey freezes the environment. The phase becomes stopped. The runtime waits up to 5 s for the running tick to end, keeps everything for the next start and tells every connected client with engineStatus and the phase stopped. The WebSocket connections stay open, the snapshot and the other routes of 3.4.8 Observation answer, and events that clients send wait for the start. Uploads and settings stay refused as after runEnvironment. Stopping a stopped environment, or one that was never started, changes nothing and answers 200. The environment stays frozen until it is dropped or the runtime ends. The WebSocket connections close when the environment is dropped, with code 1000 and the reason Environment dropped, or when the runtime itself ends, with code 1001 and the reason Runtime stopped.
Before runEnvironment, startEnvironment and stopEnvironment answer 409 with Environment with key '<envKey>' has no execution thread.
POST /setActiveState with envKey, modelElement and state forces the state machine instance of modelElement into state, also an instance that joined during the run, as 3.1.11 Forcing a state describes. It answers 409 with Environment with key <envKey> is not active before runEnvironment, and 400 with No state machine for model element '<modelElement>' in environment <envKey> or Unknown state '<state>' for model element '<modelElement>'. While the environment is stopped, the state is applied at the first tick after the start. A state inside a container state is named with its qualified name, such as self test/lit, and a container state goes down into its fragment, as 3.1.14.2 Qualified names describes.
curl -X POST "http://127.0.0.1:8080/runEnvironment?envKey=env-1763035112345"
curl -X POST "http://127.0.0.1:8080/startEnvironment?envKey=env-1763035112345"
curl -X POST "http://127.0.0.1:8080/setActiveState?envKey=env-1763035112345&modelElement=lamp&state=dimmer"
curl -X POST "http://127.0.0.1:8080/stopEnvironment?envKey=env-1763035112345"
3.4.8 Observation#
GET /observatory/environments lists every environment that was run, also stopped ones, with the keys of the objects that have state machine instances, in the order in which they step. Before the first start these are the instances the start will build, afterwards those of the latest tick:
[{"envKey":"env-1763035112345","modelElements":["lamp","wallSwitch"]}]
GET /observatory/statemachine with envKey and modelElement answers the KStates text of the state machine of the object: the text of the attachable state machine its instance runs, or else the text uploaded for it with attachedTo, or 400 with No state machine source found for model element '<modelElement>' in environment <envKey>. With name instead of modelElement it answers the text of the attachable state machine or the fragment of that name, or 400 with No attachable state machine named '<name>' in environment <envKey>. Without both it answers 400 with Missing required parameter: modelElement.
GET /observatory/stateMachines with envKey answers, as JSON with the content type application/json, what the environment holds: the keys of the attached state machines and the attachable state machines with their types, both in upload order, and the instances in the order in which they step, each with the key of its object and the name of its definition, null for an attached state machine. Before runEnvironment the list of instances is empty. The route works in every phase.
{"attached":["living room"],"definitions":[{"name":"glowing","types":["Bulb"]},{"name":"blinking","types":["Bulb"]}],"instances":[{"modelElement":"living room","stateMachine":null},{"modelElement":"bulb","stateMachine":"glowing"}]}
POST /observatory/registerClient with clientId, envKey and modelElement registers a client for the WebSocket like registerClientForWebSocket and answers an access key. The client also gets the message stateChange of the state machine attached to modelElement, or of all state machines when modelElement is *. The route works in every phase.
GET /observatory/model with envKey answers the whole model of the environment as JSON with the content type application/json; charset=UTF-8:
{"environmentKey":"env-1763035112345","phase":"configuring","revision":0,"activeStates":{},"stateMachines":{},"roots":[{"__id__": "living room", "__type__": "Room", "lamp": {"__id__": "lamp", "__type__": "Lamp", "mode": "off", "bulb": {"__id__": "bulb", "__type__": "Bulb", "maxWatts": 40, "watts": 0, "lit": false}, "spare": {"__id__": "spare", "__type__": "Bulb", "maxWatts": 60, "watts": 0, "lit": false}, "control": {"__id__": "wallSwitch", "__type__": "Switch", "position": "down"}}, "switch": {"__id__": "wallSwitch", "__type__": "Switch", "position": "down"}}]}
| Entry | Meaning |
|---|---|
environmentKey | The key of the environment |
phase | configuring, activated, running, halted or stopped, as 3 Execution describes |
revision | The revision of the last change the snapshot contains, 0 before the first change |
activeStates | For each object with a state machine instance, the last reported stack, with the qualified names of 3.1.14.2 inside container states. Empty before the first tick. An object leaves it when its instance leaves |
stateMachines | For each object with a state machine instance, the name of its definition, null for an attached state machine. Empty before the first start |
roots | The objects at the top of the model, written like the value of the message objectChanged |
In the phase configuring the snapshot is the uploaded model at revision 0, and without a model the route answers 409 with Environment with key <envKey> has no model. In the other phases the runtime reads the model between two ticks, also while a breakpoint halts the run. When no tick ends within 10 s, the route answers 409 with Environment with key <envKey> did not reach a tick boundary within 10000 ms. A model in which an object reaches itself over its relations cannot be written as JSON; the route answers 409 with Reference loop through object '<key>' cannot be written as JSON.
POST /observatory/subscribeModel with envKey and clientId lets the client get objectChanged and objectDeleted for every object of the model and stateChange for every state machine. The client must be connected to the WebSocket of the environment; otherwise the route answers 409 with Client <clientId> has no open WebSocket session for environment <envKey>. The subscription stays when the client connects again. POST /observatory/unsubscribeModel with the same parameters ends it; it answers 200 also when there was none. Both work in every phase. How a client keeps a copy of the whole model with a snapshot and these messages is in 3.5 WebSocket.
3.4.9 Health#
GET /health answers {"status":"ok"} with the content type application/json while the runtime runs.
3.4.10 Features#
| Route | Parameters | Answer |
|---|---|---|
GET /getRegisteredFeatures | The names of all features, separated by commas | |
GET /getActiveFeatures | envKey | The names of the features on in the environment, separated by commas |
POST /activateFeature | envKey, featureName | Empty |
POST /deactivateFeature | envKey, featureName | Empty |
POST /sendMessageToFeature | envKey, featureName, the message as body | The answer of the feature |
The features and their messages are in 3.2 Runtime features. The order of the names in the answers is not fixed. All routes work in every phase. The errors, all with status 400:
| Text | When |
|---|---|
Feature '<name>' is not registered | The name is no feature |
Feature '<name>' is already active in environment <envKey> | activateFeature for a feature that is on |
Feature '<name>' is not active in environment <envKey> | deactivateFeature for a feature that is off |
<name> has not been activated in environment <envKey> | sendMessageToFeature to a feature that is off |
curl "http://127.0.0.1:8080/getRegisteredFeatures"
History,TickLimit,TickByTick,Breakpoint,EventRecording,EventInjection,EventReplayController,TrueParallel
3.4.11 Whole session#
A session that runs the lamp, steps it and watches the bulb, from the folder examples/lamp of the IDE:
R=http://127.0.0.1:8080
ENV=$(curl -s -X POST "$R/createEnvironment")
curl -X PUT "$R/setMetamodel?envKey=$ENV" --data-binary @lamp.kmeta
curl -X PUT "$R/setModel?envKey=$ENV" --data-binary @lamp.kmodel
curl -X PUT "$R/setEventDefinitions?envKey=$ENV" --data-binary @lamp-events.kmeta
curl -X PUT "$R/setStateMachine?envKey=$ENV&attachedTo=lamp" --data-binary @lamp.kstates
curl -X PUT "$R/setStateMachine?envKey=$ENV&attachedTo=wallSwitch" --data-binary @switch.kstates
curl -X POST "$R/setTickDelay?envKey=$ENV&milliseconds=500"
curl -X POST "$R/setEventTtl?envKey=$ENV&ttlMs=5000"
KEY=$(curl -s -X POST "$R/registerClientForWebSocket?clientId=panel&envKey=$ENV")
curl -X POST "$R/registerObjectObserver?envKey=$ENV&clientId=panel&objectId=bulb"
curl -X POST "$R/activateFeature?envKey=$ENV&featureName=TickByTick"
curl -X POST "$R/runEnvironment?envKey=$ENV"
The client panel now connects to ws://127.0.0.1:8080/ws and sends panel:<ENV>:<KEY> as its first frame. Then:
curl -X POST "$R/startEnvironment?envKey=$ENV"
curl -X POST "$R/sendMessageToFeature?envKey=$ENV&featureName=TickByTick" -d "pause"
The client sends a press over the WebSocket:
{"environmentKey": "switch", "messageType": "press", "payload": ""}
curl -X POST "$R/sendMessageToFeature?envKey=$ENV&featureName=TickByTick" -d "tick:2"
curl "$R/observatory/model?envKey=$ENV"
curl -X POST "$R/stopEnvironment?envKey=$ENV"
Within the two ticks the lamp switches on. The client gets objectChanged for bulb after the ENTRY block of on, with lit true, and after the ENTRY block of full, with watts 40. The snapshot shows mode on and the stack on, full of the lamp.
When the client no longer needs the run, it drops the environment, and its WebSocket connection closes with code 1000 and the reason Environment dropped:
curl -X POST "$R/dropEnvironment?envKey=$ENV"