[API Specifications] Simulations

Creating simulations

Creation with POST

When invoking the API using the POST HTTP method, the service will always attempt to create a new simulation. Since the service allows to create only one simulation, retrying the request will result in errors after the first request has been successfully completed.

POST /v1/simulations

{
  "Enabled": <true|false>,
  "DeviceModels": [
    {
      "Id": "<model ID>",
      "Count": <count>
    },
    {
      "Id": "<model ID>",
      "Count": <count>
    },
    ...
  ]
}

Creation and Editing with PUT

When invoking the API using the PUT HTTP method, the service will attempt to modify an existing simulation, creating a new one if the Id does not match any existing simulation. When using PUT, the simulation Id is passed through the URL. PUT requests are idempotent and don't generate errors when retried (unless the payload differs during a retry, in which case the Etag mismatch will generate an error).

PUT /v1/simulations/1

{
  "Enabled": <true|false>,
  "DeviceModels": [
    {
      "Id": "<model ID>",
      "Count": <count>
    },
    {
      "Id": "<model ID>",
      "Count": <count>
    },
    ...
  ]
}

Create default simulation

The default simulation can be created without passing any input data, in which case the simulation created starts immediately. A client can however specify the status explicitly if required, for example to create the simulation without starting it. The format of the response remains the same.

Case 1

Request:

POST /v1/simulations?template=default
Content-Type: application/json; charset=utf-8

Case 2

Request:

POST /v1/simulations?template=default
Content-Type: application/json; charset=utf-8

{ "Enabled": false }

Response:

200 OK
Content-Type: application/json; charset=utf-8

{
  "Etag": "969ee1fb277640",
  "Id": "1",
  "Enabled": true,
  "DeviceModels": [
    {
      "Id": "truck-01",
      "Count": 1
    },
    {
      "Id": "engine-02",
      "Count": 1
    },
    {
      "Id": "truck-02",
      "Count": 1
    },
    {
      "Id": "engine-01",
      "Count": 1
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/1",
    "$version": "1",
    "$created": "2017-05-31T01:21:37+00:00",
    "$modified": "2017-05-31T01:21:37+00:00"
  }
}

Create simulation passing in a list of device models and device count

A client can create a simulation different from the default template, for example specifying which device models and how many devices to simulate.

Request:

POST /v1/simulations
Content-Type: application/json; charset=utf-8

{
  "Enabled": true,
  "DeviceModels": [
    {
      "Id": "truck-01",
      "Count": 3
    },
    {
      "Id": "truck-02",
      "Count": 1
    },
    {
      "Id": "elevator-01",
      "Count": 10
    }
  ]
}

Response:

200 OK
Content-Type: application/json; charset=utf-8

{
  "Etag": "cec0722b205740",
  "Id": "1",
  "Enabled": true,
  "DeviceModels": [
    {
      "Id": "truck-01",
      "Count": 3
    },
    {
      "Id": "truck-02",
      "Count": 1
    },
    {
      "Id": "elevator-01",
      "Count": 10
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/1",
    "$version": "1",
    "$created": "2017-05-31T00:47:18+00:00",
    "$modified": "2017-05-31T00:47:18+00:00"
  }
}

Get details of the running simulation, including device models

Request:

GET /v1/simulations/1

Response:

200 OK
Content-Type: application/json; charset=utf-8

{
  "Etag": "cec0722b205740",
  "Id": "1",
  "Enabled": true,
  "DeviceModels": [
    {
      "Id": "truck-01",
      "Count": 3
    },
    {
      "Id": "truck-02",
      "Count": 1
    },
    {
      "Id": "elevator-01",
      "Count": 10
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/1",
    "$version": "1",
    "$created": "2017-05-31T00:47:18+00:00",
    "$modified": "2017-05-31T00:47:18+00:00"
  }
}

Start simulation

In order to start a simulation, the Enabled property needs to be changed to true. While it's possible to use the PUT HTTP method, and edit the entire simulation object, the API supports also the PATCH HTTP method, so that a client can send a smaller request. In both cases the client should send the correct Etag, to manage the optimistic concurrency.

Request:

PATCH /v1/simulations/1
Content-Type: application/json; charset=utf-8

{
  "Etag": "cec0722b205740",
  "Enabled": true
}

Response:

200 OK
Content-Type: application/JSON

{
  "Etag": "8602d62c271760",
  "Id": "1",
  "Enabled": true,
  "DeviceModels": [
    {
      "Id": "truck-01",
      "Count": 3
    },
    {
      "Id": "truck-02",
      "Count": 1
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/1",
    "$version": "2",
    "$created": "2017-05-31T00:47:18+00:00",
    "$modified": "2017-05-31T00:47:18+00:00"
  }
}

Stop simulation

In order to stop a simulation, the Enabled property needs to be changed to false. While it's possible to use the PUT HTTP method, and edit the entire simulation object, the API supports also the PATCH HTTP method, so that a client can send a smaller request. In both cases the client should send the correct Etag, to manage the optimistic concurrency.

Visibility: public; Auth: requires Admin

Request:

PATCH /v1/simulations/1
Content-Type: application/json; charset=utf-8

{
  "Etag": "8602d62c271760",
  "Enabled": false
}

Response:

200 OK
Content-Type: application/JSON

{
  "Etag": "930a9aea201193",
  "Id": "1",
  "Enabled": false,
  "DeviceModels": [
    {
      "Id": "truck-01",
      "Count": 3
    },
    {
      "Id": "truck-02",
      "Count": 1
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/1",
    "$version": "3",
    "$created": "2017-05-31T00:47:18+00:00",
    "$modified": "2017-05-31T00:50:59+00:00"
  }
}

Modifying a running simulation

Simulations can be modified by calling PUT and passing the existing simulation ID. This can be coupled with a GET to pull the existing simulation content, editing it, then calling PUT with the modification(s).