[API Specifications] Simulations

Creating simulations

Normally, when creating a simulation, a client doesn't need to speficy the simuation Id, and the backend generates a random Id automatically. However, the service allows to pass an explicit Id, which can be useful where idempotent requests are preferred, e.g. in case of retriable requests.

Creation with POST

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

POST /v1/simulations

...data...

Creation with PUT

Whe 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/my-custom-id

...data...

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.

Visibility: public; Auth: requires Viewer|Admin

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": "8ec9653b-973c-4220-81f1-e44e1c7f1617",
  "Enabled": true,
  "DeviceTypes": [
    {
      "Id": "11110000-1111-0000-0000-000011110000",
      "Count": 2
    },
    {
      "Id": "22220000-2222-0000-0000-000022220000",
      "Count": 2
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/8ec9653b-973c-4220-81f1-e44e1c7f1617",
    "$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 types and device count

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

Visibility: public; Auth: requires Viewer|Admin

Request:

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

{
  "Enabled": true,
  "DeviceTypes": [
    {
      "Id": "11110000-1111-0000-0000-000011110000",
      "Count": 3
    },
    {
      "Id": "22220000-2222-0000-0000-000022220000",
      "Count": 1
    }
  ]
}

Response:

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

{
  "Etag": "cec0722b205740",
  "Id": "c61116d9-40ed-418b-8c1b-327dfabbc06e",
  "Enabled": true,
  "DeviceTypes": [
    {
      "Id": "11110000-1111-0000-0000-000011110000",
      "Count": 3
    },
    {
      "Id": "22220000-2222-0000-0000-000022220000",
      "Count": 1
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/c61116d9-40ed-418b-8c1b-327dfabbc06e",
    "$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 types

Visibility: public; Auth: requires Viewer|Admin

Request:

GET /v1/simulations/21aa6478-b888-4c5d-8bf0-0dacaee99191

Response:

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

{
  "Etag": "cec0722b205740",
  "Id": "c61116d9-40ed-418b-8c1b-327dfabbc06e",
  "Enabled": true,
  "DeviceTypes": [
    {
      "Id": "11110000-1111-0000-0000-000011110000",
      "Count": 3
    },
    {
      "Id": "22220000-2222-0000-0000-000022220000",
      "Count": 1
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/c61116d9-40ed-418b-8c1b-327dfabbc06e",
    "$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.

Visibility: public; Auth: requires Admin

Request:

PATCH /v1/simulation/21aa6478-b888-4c5d-8bf0-0dacaee99191
Content-Type: application/json; charset=utf-8

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

Response:

200 OK
Content-Type: application/JSON

{
  "Etag": "8602d62c271760",
  "Id": "c61116d9-40ed-418b-8c1b-327dfabbc06e",
  "Enabled": true,
  "DeviceTypes": [
    {
      "Id": "11110000-1111-0000-0000-000011110000",
      "Count": 3
    },
    {
      "Id": "22220000-2222-0000-0000-000022220000",
      "Count": 1
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/c61116d9-40ed-418b-8c1b-327dfabbc06e",
    "$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/simulation/21aa6478-b888-4c5d-8bf0-0dacaee99191
Content-Type: application/json; charset=utf-8

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

Response:

200 OK
Content-Type: application/JSON

{
  "Etag": "930a9aea201193",
  "Id": "21aa6478-b888-4c5d-8bf0-0dacaee99191",
  "Enabled": false,
  "DeviceTypes": [
    {
      "Id": "11110000-1111-0000-0000-000011110000",
      "Count": 3
    },
    {
      "Id": "22220000-2222-0000-0000-000022220000",
      "Count": 1
    }
  ],
  "$metadata": {
    "$type": "Simulation;1",
    "$uri": "/v1/simulations/c61116d9-40ed-418b-8c1b-327dfabbc06e",
    "$version": "3",
    "$created": "2017-05-31T00:47:18+00:00",
    "$modified": "2017-05-31T00:50:59+00:00"
  }
}