# Systems

The `/systems` endpoint provides methods for discovering, creating and interacting with systems. For more on the role that systems play, see:

{% content-ref url="../../key-concepts/systems" %}
[systems](https://engine.place.technology/key-concepts/systems)
{% endcontent-ref %}

All systems provide a base set of metadata that helps to describe their role and capabilities, as well as provide references to the modules they contain, and the zones they exist in.

## Model

| Attribute              | Type      | Description                                                                                |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------ |
| id                     | `string`  | The system's unique ID.                                                                    |
| edge\_id               | `string`  | ID of the preferred engine node to run on.                                                 |
| name                   | `string`  | The system's primary identifier.                                                           |
| zones                  | `array`   | Zone IDs that this system is a member of.                                                  |
| modules                | `array`   | Module ID's that this system contains.                                                     |
| description            | `string`  | Markdown formatted text that describes the system.                                         |
| email                  | `string`  | Calendar email that represents this system. Typically used for room scheduling / bookings. |
| capacity               | `integer` | Number of people this space can accommodate.                                               |
| features               | `string`  | List of features in the room for searching and filtering spaces.                           |
| bookable               | `boolean` | Flag for signifying the space is bookable.                                                 |
| installed\_ui\_devices | `integer` | Expected number of fixed installation touch panels.                                        |
| settings               | `object`  | JSON object representing the system's configuration.                                       |
| created\_at            | `integer` | Timestamp of creation.                                                                     |
| support\_url           | `string`  | A URL linking to the primary interface for controlling this system.                        |
| version                | `integer` | Incremental counter for handling stale updates.                                            |

## Discovery

## Search

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/systems`

Direct queries to the systems endpoint list, or search for existing systems.

#### Query Parameters

| Name       | Type    | Description                                |
| ---------- | ------- | ------------------------------------------ |
| q          | string  | A search query for the system metadata.    |
| limit      | integer | Max results to return (default 20).        |
| offset     | integer | The offset within the result set.          |
| zone\_id   | string  | Limit to systems within this zone.         |
| module\_id | string  | Limit to systems that contain this module. |

{% tabs %}
{% tab title="200 A list of systems matching the search criteria." %}

```javascript
{
    "total": 3,
    "results": [
        {
            "edge_id": "edge-QC03B3OM",
            "name": "Room 1",
            "description": null,
            "email": "room1@example.com",
            "capacity": 10,
            "features": "",
            "bookable": true,
            "installed_ui_devices": 0,
            "zones": [
                "zone-rGhCRp_aUD"
            ],
            "modules": [
                "mod-rJRCVYKVuB",
                "mod-rJRGK21pya",
                "mod-rJRHYsZExU"
            ],
            "settings": {},
            "created_at": 1562041110,
            "support_url": null,
            "version": 5,
            "id": "sys-rJQQlR4Cn7"
        },
        {
            "edge_id": "edge-QC03B3OM",
            "name": "Room 2",
            "description": null,
            "email": "room2@example.com",
            "capacity": 10,
            "features": "",
            "bookable": true,
            "installed_ui_devices": 0,
            "zones": [
                "zone-rGhCRp_aUD"
            ],
            "modules": [
                "mod-rJRJOM27Kb",
                "mod-rJRLE4_PQ7",
                "mod-rJRLwe72Mo"
            ],
            "settings": {},
            "created_at": 1562041127,
            "support_url": null,
            "version": 4,
            "id": "sys-rJQSySsELE"
        },
        {
            "edge_id": "edge-QC03B3OM",
            "name": "Room 3",
            "description": null,
            "email": "room3@example.com",
            "capacity": 4,
            "features": "",
            "bookable": true,
            "installed_ui_devices": 0,
            "zones": [
                "zone-rGhCRp_aUD"
            ],
            "modules": [
                "mod-rJRNrLDPNz",
                "mod-rJRQ~JwE7U",
                "mod-rJRV1qokbH"
            ],
            "settings": {},
            "created_at": 1562041145,
            "support_url": null,
            "version": 4,
            "id": "sys-rJQVPIR9Uf"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

Queries default to searching for any of the entered terms (words). A small query language provides the ability to structure complex queries.

| Operator    | Action                                            |                       |
| ----------- | ------------------------------------------------- | --------------------- |
| `+`         | Matches both terms.                               |                       |
| \`          | \`                                                | Matches either terms. |
| `-`         | Negates a single token.                           |                       |
| `"`         | Wraps tokens to form a phrase.                    |                       |
| `(` and `)` | Provide precedence.                               |                       |
| `~N`        | Specifies edit distance (fuzziness) after a word. |                       |
| `~N`        | Specifies slop amount (deviation) after a phrase. |                       |

## Management

## Create

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/systems`

Defines a new system. Systems names must be unique within the instance they are running on and all systems must have at least one zone associated. All other attributes are optional at the time of creation.

#### Request Body

| Name                   | Type    | Description |
| ---------------------- | ------- | ----------- |
| name                   | string  |             |
| zones                  | array   |             |
| edge\_id               | string  |             |
| description            | string  |             |
| email                  | string  |             |
| capacity               | integer |             |
| bookable               | boolean |             |
| installed\_ui\_devices | integer |             |
| modules                | string  |             |
| settings               | string  |             |
| support\_url           | string  |             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further cotnext",
    "email": "room@example.com",
    "capacity": 10,
    "features": "",
    "bookable": true,
    "installed_ui_devices": 0,
    "zones": [
        "zone-rGhCRp_aUD"
    ],
    "modules": [],
    "settings": {},
    "created_at": 1562041110,
    "support_url": "https://example.com/foo",
    "id": "sys-rJQQlR4Cn7"
}
```

{% endtab %}
{% endtabs %}

## Retrieve

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/systems/{id}`

Retrieve all metadata associated with the system.

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | ID of the system to retrieve. |

#### Query Parameters

| Name     | Type    | Description                                                                                   |
| -------- | ------- | --------------------------------------------------------------------------------------------- |
| complete | boolean | Include full models of all modules and zones associated with the system rather than their ID. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further context",
    "email": "room@example.com",
    "capacity": 10,
    "features": "",
    "bookable": true,
    "installed_ui_devices": 0,
    "zones": [
        "zone-rGhCRp_aUD"
    ],
    "modules": [
        "mod-rJRCVYKVuB",
        "mod-rJRGK21pya",
        "mod-rJRHYsZExU"
    ],
    "settings": {},
    "created_at": 1562041110,
    "support_url": "https://example.com/foo",
    "version": 3,
    "id": "sys-rJQQlR4Cn7"
}
```

{% endtab %}
{% endtabs %}

## Update

<mark style="color:orange;">`PUT`</mark> `https://example.com/api/control/systems/{id}`

Updates system attributes. Any selection of attributes form the request - unspecified items will keep their current values. All requests must include a **version** parameter that matches the current system version.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | ID of the system to update. |

#### Request Body

| Name                   | Type    | Description                                                                                                       |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| version                | integer | The system metadata version. This must match the current version and increments following each successful update. |
| name                   | string  |                                                                                                                   |
| description            | string  |                                                                                                                   |
| email                  | string  |                                                                                                                   |
| capacity               | integer |                                                                                                                   |
| bookable               | boolean |                                                                                                                   |
| installed\_ui\_devices | integer |                                                                                                                   |
| zones                  | array   |                                                                                                                   |
| modules                | string  |                                                                                                                   |
| settings               | string  |                                                                                                                   |
| support\_url           | string  |                                                                                                                   |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further context",
    "email": "room@example.com",
    "capacity": 10,
    "features": "",
    "bookable": true,
    "installed_ui_devices": 0,
    "zones": [
        "zone-rGhCRp_aUD"
    ],
    "modules": [],
    "settings": {},
    "created_at": 1562041110,
    "support_url": "https://example.com/foo",
    "id": "sys-rJQQlR4Cn7"
}
```

{% endtab %}

{% tab title="409 The specified version does not match the current system version." %}

```
```

{% endtab %}
{% endtabs %}

## Delete

<mark style="color:red;">`DELETE`</mark> `https://example.com/api/control/systems/{id}`

Removes a system. This will stop, and remove any modules that are not associated with other systems.

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | ID of the system to retrieve. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Interaction

## Start

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/systems/{id}/start`

Starts all modules associated with the system.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the system to start. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Stop

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/systems/{id}/stop`

Stops all modules associated with the system.

#### Path Parameters

| Name | Type   | Description               |
| ---- | ------ | ------------------------- |
| id   | string | ID of the system to stop. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Exec

<mark style="color:green;">`POST`</mark> `https://example.com/api/control/systems/{id}/exec`

Run behaviour exposed by a module. The associated method will execute and the response returned. If this includes asynchronous or long running behaviour, the result will be awaiting up until a timeout value.

#### Path Parameters

| Name | Type   | Description                          |
| ---- | ------ | ------------------------------------ |
| id   | string | ID of the system to execute within.a |

#### Request Body

| Name   | Type    | Description                                                  |
| ------ | ------- | ------------------------------------------------------------ |
| module | string  | Class name of the module. i.e. \`Display\`, \`Bookings\` etc |
| index  | integer | (default 1) Module index in the system.                      |
| method | string  | The name of the method to execute.                           |
| args   | array   | Method arguments.                                            |

{% tabs %}
{% tab title="200 Response values are always wrapped in an outer array. This ensures that method which return primatives (strings, numbers, booleans or null) still provide a valid JSON response." %}

```javascript
[]
```

{% endtab %}
{% endtabs %}

## State

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/systems/{id}/state`

Query the state exposed by a module within the system.

#### Path Parameters

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| id   | string | ID of the system the module is in. |

#### Query Parameters

| Name   | Type    | Description                                                                |
| ------ | ------- | -------------------------------------------------------------------------- |
| module | string  | Class name of the module.                                                  |
| index  | integer | (default 1) Index of the module.                                           |
| lookup | string  | A status key of interest. If included, the response filters to this value. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "foo": "abc",
  "bar": 42
}
```

{% endtab %}
{% endtabs %}

## Funcs

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/systems/{id}/funcs`

Query the behaviour exposed by a module within the system.

#### Path Parameters

| Name | Type   | Description                             |
| ---- | ------ | --------------------------------------- |
| id   | string | ID of the system that the module is in. |

#### Query Parameters

| Name   | Type    | Description                      |
| ------ | ------- | -------------------------------- |
| module | string  | Class of the module.             |
| index  | integer | (default 1) Index of the module. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "function_name": {
    "arity": 1,
    "params": [
      "string"
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Count

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/systems/{id}/count`

Counts the instances of a driver type within a system.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the system to query. |

#### Query Parameters

| Name   | Type   | Description                         |
| ------ | ------ | ----------------------------------- |
| module | string | Class name of the modules to count. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "count": 3
}
```

{% endtab %}
{% endtabs %}

## Types

<mark style="color:blue;">`GET`</mark> `https://example.com/api/control/systems/{id}/types`

Query the types of modules available within a system.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the system to query. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "Booking": 1,
  "Display": 2,
  "VidConf": 1
}
```

{% endtab %}
{% endtabs %}