Create a new runtime

Creates a new runtime on the platform. A runtime contains actors and links between those actors.

JSON input

{
  "name": string,
  ("owner": string or UUID),
  ("projectid": UUID),
  "actors": [
     <actor_def>, ...
  ], "links": [
    <link_def>, ...
  ], 
  ("distribution": {
    <distribution>
  })
}

<actor_def>:
{
  "name": string,
  "type": string,
  "params": {
    <actor_params>
  }
}

<link_def>: 
{
  "from": string, "to": string
}

<distribution>:
{
  "mode": <mode>,
  ("copies": int,)
  ("machines": (<mode> | <machine_array>),) |
  ("machine": <machine_def>)
}

<machine_array>: [<machine_def>, ...]
  
<machine_def>:
{
  "ip": string,
  "port": int
}

<mode>: "predefined" | "duplicate" | 
  "local" | "round-robin" | 
  "random" | "least-nr-actors" | 
  "least-nr-runtimes" | "least-busy"

The “owner” field is optional, and can be either the unique name of the user or an UUID. If no owner field is provided, the current owner is assumed. When “accept-all” authentication is used, a user with the name “coral” is assumed. If the specified owner is not equal to the currently logged in user, the request is rejected. This may be changed in future releases, when a runtime on behalf of another user can be created.

The projectid is optional and is a planned future feature of the Coral platform. Currently, it is not used. The “actors” section contains actor definitions, which can be found in the Actor Overview. The “links” section contains all links between actors. The names mentioned in “from” and “to” must be existing names in the actor definition section.

Distribution section

The distribution specification is optional and specifies the distribution mechanism of the runtime on the Coral platform. The mode field can be any of ones specified here. The “machine” field is only necessary when the “predefined” mode is used. If no distribution section is present, the platform distribution settings will be used and a single copy will be instantiated.

The field mode in the distribution section specifies what the distribution setting for the runtime copies is. It can be either duplicate or predefined.

In the case of duplicate, the machines field can either be:

• The name of the distribution setting, as specified here: local, round-robin, random, least-nr-actors, least-nr-runtimes or least-busy.

{
  "distribution": {
    "mode": "duplicate",
    "copies": 5,
    "machines": "round-robin"   
  }
}

• or, an array of machines:

{
  "distribution": {
    "mode": "duplicate",
    "copies": 2,
    "machines": [{
      "ip": "153.253.36.85",
      "port": 2551
    }, {
      "ip": "173.142.26.31",
      "port": 2551
    }]
  }
}

In the case of predefined, the machines field is a single machine:

{
  "distribution": {
    "mode": "predefined",
    "machine": {
      "ip": "127.0.0.1",
      "port": 2551
    }
  }
}

Below, an example of a distribution section of a new runtime is shown, which deploys five runtime copies on five different machines in round-robin fashion.

{
   ...,
   "distribution": {
      "mode": "duplicate",
      "copies": 5,
      "machines": "round-robin"   
   }
}

Example

{
  "name": "runtime1",
  "owner": "neo",
  "actors": [{
    "name": "generator1",
    "type": "generator",
      "params": {
        "format": {
          "field1": "Hello, world!"
        }, "timer": {
          "rate": 10
        }
      }
    }, {
      "name": "log1",
      "type": "log",
      "params": {
        "file": "/tmp/runtime1.log"
      }
  }], "links": [
    { "from": "generator1", "to": "log1" }
  ], 
  "distribution": {
    "mode": "predefined",
      "machine": {
        "ip": "127.0.0.1",
        "port": 2551
      }
    }
}

This will create a new runtime which is deployed on machine 127.0.0.1 with port 2551. Since only a single machine is provided and no copies argument is given, a single copy is assumed.

JSON output

When successful:

{
  "success": true,
  "created": datetime,
  "id": UUID,
  "definition": json
}

The platform returns the time of creation of the runtime, a unique identifier for the created runtime and the definition that you have posted.

On failure:

{
  "success": false,
  "reason": string,
  "details": string
}

When the API call fails, the platform returns the reason of the failure and a stack trace of the failure.

Example

When successful:

{
  "success": true,
  "created": "2015-12-29T15:39:51",
  "id": "5572fdda-34a4-4d8f-8a6a-77ae36e1e3e5",
  "definition": <json definition>
}

On failure:

{
  "success": false,
  "reason": "Owner with name neo not found."
  "details": "<stacktrace>"
}

Errors

Invalid runtime definition

A runtime definition can be invalid for several reasons:

• There is no valid actors section present. The “actors” array field is missing in your JSON definition. Make sure you have an “actors” section in your definition.
• There are no actors present in the actors section. The “actors” array field is present in your JSON definition, but it does not contain any actor definitions. Make sure that the “actors” section is not empty.
• There are actors without names. Make sure that each actor has a “name” field.
• The configuration does not have a runtime name specified in the “name” field. Make sure the “name” field in the top level of the JSON object is present.
• There are actors with duplicate names. Make sure that every actor has a unique name.
• There are invalid actor definitions. Check each actor definition against the specification of that actor.
• There is no valid links section present. Make sure a “links” section is present in the definition.
• There are no links present in the links section. The “links” section is present, but the array is empty. Make sure that the “links” section contains at least one link.
• There are links without a “from” and “to” attribute. Each link should have both a “from” and a “to” field.
• Not all actors mentioned in the links are actual actor names in the configuration. Make sure that all actors mentioned in the links section are defined in the actor section. The “from” or “to” field should match the “name” section of exactly one actor.
• There are actors which are not being referenced in any from or to field of the links section. Make sure that each actor is connected at least once.
• There are actors with types which do not refer to any existing actor (see Actor Overview). Make sure each actor type refers to an actually existing actor.

If you encounter any of these errors, check your runtime definition carefully and submit your runtime again if you have fixed the errors.