Calvin Control API

Calvin Control API

• Get documentation in 'raw' format for actor or module at {path}

    GET /actor_doc {path}
    Path is formatted as '/{module}/{submodule}/ ... /{actor}'.
    If {path} is empty return top-level documentation.
    See DocumentStore help_raw() for details on data format.
    Response status code: OK
    Response: dictionary with documentation

• Register for log events and set actor and event filter.

    POST /log
    Body:
    {
        'user_id': <user_id>     # Optional user id
        'actors': [<actor-id>],  # Actors to log, empty list for all
        'events': [<event_type>] # Event types to log: actor_firing, action_result,
                                                       actor_new, actor_destroy, actor_migrate,
                                                       application_new, application_destroy
    }
    Response status code: OK or BAD_REQUEST
    Response:
    {
        'user_id': <user_id>,
        'epoch_year': <the year the epoch starts at Jan 1 00:00, e.g. 1970>
    }

• Unregister for trace data

    DELETE /log/{user-id}
    Response status code: OK or NOT_FOUND

• Get streamed log events

    GET /log/{user-id}
    Response status code: OK or NOT_FOUND
    Content-Type: text/event-stream
    data:
    {
        'timestamp': <timestamp>,
        'node_id': <node_id>,
        'type': <event_type>, # event types: actor_fire, actor_new, actor_destroy, actor_migrate, application_new, application_destroy
        'actor_id',           # included in: actor_fire, actor_new, actor_destroy, actor_migrate
        'actor_name',         # included in: actor_new
        'actor_is_shadow'     # included in: actor_new
        'action_method',      # included in: actor_fire
        'consumed',           # included in: actor_fire
        'produced'            # included in: actor_fire
        'action_result'       # included in: actor_fire
        'actor_type',         # included in: actor_new
        'dest_node_id',       # included in: actor_migrate
        'application_name',   # included in: application_new
        'application_id'      # included in: application, application_destroy
    }

• Get id of this calvin node

    GET /id
    Response status code: OK
    Response: node-id

• Get capabilities of this calvin node

    GET /capabilities
    Response status code: OK
    Response: list of capabilities

• List nodes in network (excluding self) known to self

    GET /nodes
    Response status code: OK
    Response: List of node-ids

• Get information on node node-id

    GET /node/{node-id}
    Response status code: OK or NOT_FOUND
    Response:
    {
        "attributes": {...},
        "control_uri": "http(s)://<address>:<controlport>",
        "uri": "calvinip://<address>:<port>"
    }

• Set indexed_public attributes on node with node-id

    POST /node/{node-id}/attributes/indexed_public
    Body:
    {
        "node_name": {"organization": <organization>, "organizationalUnit": <organizationalUnit>, "purpose": <purpose>, "group": <group>, "name": <name>},
        "owner": {"organization": <organization>, "organizationalUnit": <organizationalUnit>, "role": <role>, "personOrGroup": <personOrGroup>},
        "address": {"country": <country>, "stateOrProvince": <stateOrProvince>, "locality": <locality>, "street": <street>, "streetNumber": <streetNumber>, "building": <building>, "floor": <floor>, "room": <room>}
    }
    Response status code: OK, UNAUTHORIZED or INTERNAL_ERROR

• Add calvin nodes to network

    POST /peer_setup
    Body: {"peers: ["calvinip://<address>:<port>", ...] }
    Response status code: OK or SERVICE_UNAVAILABLE
    Response: {<peer control uri>: [<peer node id>, <per peer status>], ...}

• Get applications launched from this node

    GET /applications
    Response status code: OK
    Response: List of application ids

• Get information on application application-id

    GET /application/{application-id}
    Response status code: OK or NOT_FOUND
    Response:
    {
         "origin_node_id": <node id>,
         "actors": <list of actor ids>
         "name": <name or id of this application>
    }

• Stop application (only applications launched from this node)

    DELETE /application/{application-id}
    Response status code: OK, NOT_FOUND, INTERNAL_ERROR
    Response: [<actor_id>, ...] when error list of actors (replicas) in application not destroyed

• Create a new actor

    POST /actor
    Body:
    {
        "actor_type:" <type of actor>,
        "args" : { "name": <name of actor>, <actor argument>:<value>, ... }
        "deploy_args" : {"app_id": <application id>, "app_name": <application name>} (optional)
    }
    Response status code: OK or INTERNAL_ERROR
    Response: {"actor_id": <actor-id>}

• Get list of actors on this runtime

    GET /actors
    Response status code: OK
    Response: list of actor ids

• Get information on actor

    GET /actor/{actor-id}
    Response status code: OK or NOT_FOUND
    Response:
    {
        "inports": list inports
        "node_id": <node-id>,
        "type": <actor type>,
        "name": <actor name>,
        "outports": list of outports
    }

• Delete actor

    DELETE /actor/{actor-id}
    Response status code: OK or NOT_FOUND
    Response: none

• Some actor store statistics on inputs and outputs, this reports these. Not always present.

    GET /actor/{actor-id}/report
    Response status code: OK or NOT_FOUND
    Response: Depends on actor

• Migrate actor to (other) node, either explicit node_id or by updated requirements

    POST /actor/{actor-id}/migrate
    Body: {"peer_node_id": <node-id>}
    Alternative body:
    Body:
    {
        "requirements": [ {"op": "<matching rule name>",
                          "kwargs": {<rule param key>: <rule param value>, ...},
                          "type": "+" or "-" for set intersection or set removal, respectively
                          }, ...
                        ],
        "extend": True or False  # defaults to False, i.e. replace current requirements
        "move": True or False  # defaults to False, i.e. when possible stay on the current node
    }

• Response status code: OK, BAD_REQUEST, INTERNAL_ERROR or NOT_FOUND

    For further details about requirements see application deploy.
    Response: none

• DEPRECATED. Disables an actor

    POST /actor/{actor-id}/disable
    Response status code: OK or NOT_FOUND
    Response: none

• ONLY FOR TEST. Will replicate an actor directly

    POST /actor/{actor-id}/replicate
    Response status code: OK or NOT_FOUND
    Response: {'actor_id': <replicated actor instance id>}

• Connect actor ports

    POST /connect
    Body:
    {
        "actor_id" : <actor-id>,
        "port_name": <port-name>,
        "port_dir": <in/out>,
        "peer_node_id": <node-id>,
        "peer_actor_id": <actor-id>,
        "peer_port_name": <port-name>,
        "peer_port_dir": <out/in>
    }
    Response status code: OK, BAD_REQUEST, INTERNAL_ERROR or NOT_FOUND
    Response: {"peer_port_id": <peer port id>}

• Sets a property of the port.

    POST /set_port_property
    Body:
    {
        "actor_id" : <actor-id>,
        "port_type": <in/out>,
        "port_name": <port-name>,
        "port_id": <port-id>, optionally instead of the above identifiers
        "port_property": <property-name as string>
        "value" : <property value>
    }
    Response status code: OK, BAD_REQUEST or NOT_FOUND
    Response: none

• Compile and deploy a calvin script to this calvin node

    POST /deploy
    Apply deployment requirements to actors of an application
    and initiate migration of actors accordingly
    Body:
    {
        "name": <application name>,
        "script": <calvin script>  # alternativly "app_info"
        "app_info": <compiled script as app_info>  # alternativly "script"
        "sec_sign": {<cert hash>: <security signature of script>, ...} # optional and only with "script"
        "sec_credentials": <security credentials of user> # optional
        "deploy_info":
           {"groups": {"<group 1 name>": ["<actor instance 1 name>", ...]},  # TODO not yet implemented
            "requirements": {
                "<actor instance 1 name>": [ {"op": "<matching rule name>",
                                              "kwargs": {<rule param key>: <rule param value>, ...},
                                              "type": "+" or "-" for set intersection or set removal, respectively
                                              }, ...
                                           ],
                ...
                            }
           }
    }
    Note that either a script or app_info must be supplied. Optionally security
    verification of application script can be made. Also optionally user credentials
    can be supplied, some runtimes are configured to require credentials. The
    credentials takes for example the following form:
        {"user": <username>,
         "password": <password>,
         "role": <role>,
         "group": <group>,
         ...
        }

    The matching rules are implemented as plug-ins, intended to be extended.
    The type "+" is "and"-ing rules together (actually the intersection of all
    possible nodes returned by the rules.) The type "-" is explicitly removing
    the nodes returned by this rule from the set of possible nodes. Note that
    only negative rules will result in no possible nodes, i.e. there is no
    implied "all but these."

    A special matching rule exist, to first form a union between matching
    rules, i.e. alternative matches. This is useful for e.g. alternative
    namings, ownerships or specifying either of two specific nodes.
        {"op": "union_group",
         "requirements": [list as above of matching rules but without type key]
         "type": "+"
        }
    Other matching rules available is current_node, all_nodes and
    node_attr_match which takes an index param which is attribute formatted,
    e.g.
        {"op": "node_attr_match",
         "kwargs": {"index": ["node_name", {"organization": "org.testexample", "name": "testNode1"}]}
         "type": "+"
        }
    Response status code: OK, CREATED, BAD_REQUEST, UNAUTHORIZED or INTERNAL_ERROR
    Response: {"application_id": <application-id>,
               "actor_map": {<actor name with namespace>: <actor id>, ...}
               "placement": {<actor_id>: <node_id>, ...},
               "requirements_fulfilled": True/False}
    Failure response: {'errors': <compilation errors>,
                       'warnings': <compilation warnings>,
                       'exception': <exception string>}

• Update deployment requirements of application application-id

    POST /application/{application-id}/migrate
    and initiate migration of actors.
    Body:
    {
        "deploy_info":
           {"requirements": {
                "<actor instance 1 name>": [ {"op": "<matching rule name>",
                                              "kwargs": {<rule param key>: <rule param value>, ...},
                                              "type": "+" or "-" for set intersection or set removal, respectively
                                              }, ...
                                           ],
                ...
                            }
           }
    }
    For more details on deployment information see application deploy.
    Response status code: OK, INTERNAL_ERROR or NOT_FOUND
    Response: none

• Disconnect a port.

    POST /disconnect
    If port fields are empty, all ports of the actor are disconnected
    Body:
    {
        "actor_id": <actor-id>,
        "port_name": <port-name>,
        "port_dir": <in/out>,
        "port_id": <port-id>
    }
    Response status code: OK, INTERNAL_ERROR or NOT_FOUND
    Response: none

• Stop (this) calvin node

    DELETE /node{/now|/migrate}
     now: stop the runtime without handling actors on the runtime [default]
     migrate: migrate any actors before stopping the runtime
    Response status code: ACCEPTED
    Response: none

• Store value under index key

    POST /index/{key}
    Body:
    {
        "value": <string>
    }
    Response status code: OK or INTERNAL_ERROR
    Response: none

• Remove value from index key

    DELETE /index/{key}
    Body:
    {
        "value": <string>
    }
    Response status code: OK or INTERNAL_ERROR
    Response: none

• Fetch values under index key

    GET /index/{key}
    Response status code: OK or NOT_FOUND
    Response: {"result": <list of strings>}

• Fetch value under prefix-key

    GET /storage/{prefix-key}
    Response status code: OK or NOT_FOUND
    Response: {"result": <value>}

• Dump storage to temporary file in /tmp when available

    GET /dumpstorage
    Response status code: OK
    Response: none

• Store value under prefix-key

    POST /storage/{prefix-key}
    Body:
    {
        "value": <string>
    }
    Response status code: OK or INTERNAL_ERROR
    Response: none

• Send CSR to CA, that creates a x509 certificate and returns it

    POST /certiticate_authority/certificate_signing_request
    Response status code: OK or INTERNAL_ERROR
    Response:
    {"certificate":<value>}

• Get user database on this runtime

    GET /authentication/users_db
    Response status code: OK or INTERNAL_ERROR
    Response:
    {
        "policies": {
            <policy-id>: policy in JSON format,
            ...
        }
    }

• Update user database

    PUT /authentication/users_db
    Body: new policy in JSON format
    Response status code: OK, INTERNAL_ERROR or NOT_FOUND
    Response: none

• Get user database on this runtime

    GET /authentication/groups_db
    Response status code: OK or INTERNAL_ERROR
    Response:
    {
        "policies": {
            <policy-id>: policy in JSON format,
            ...
        }
    }

• Update user database

    PUT /authentication/groups_db
    Body: new policy in JSON format
    Response status code: OK, INTERNAL_ERROR or NOT_FOUND
    Response: none

• Create a new policy

    POST /authorization/policies
    Body: policy in JSON format
    Response status code: OK or INTERNAL_ERROR
    Response: {"policy_id": <policy-id>}

• Get all policies on this runtime

    GET /authorization/policies
    Response status code: OK or INTERNAL_ERROR
    Response:
    {
        "policies": {
            <policy-id>: policy in JSON format,
            ...
        }
    }

• Get policy

    GET /authorization/policies/{policy-id}
    Response status code: OK, INTERNAL_ERROR or NOT_FOUND
    Response: {"policy": policy in JSON format}

• Update policy

    PUT /authorization/policies/{policy-id}
    Body: new policy in JSON format
    Response status code: OK, INTERNAL_ERROR or NOT_FOUND
    Response: none

• Delete policy

    DELETE /authorization/policies/{policy-id}
    Response status code: OK, INTERNAL_ERROR or NOT_FOUND
    Response: none

• Request for information about the communication options available on url

    OPTIONS /url
    Response status code: OK
    Response: Available communication options