Systems

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

pageSystems

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

GET https://example.com/api/control/systems

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

Query Parameters

NameTypeDescription

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.

{
    "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"
        }
    ]
}

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

POST 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

NameTypeDescription

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

{
    "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"
}

Retrieve

GET https://example.com/api/control/systems/{id}

Retrieve all metadata associated with the system.

Path Parameters

NameTypeDescription

id

string

ID of the system to retrieve.

Query Parameters

NameTypeDescription

complete

boolean

Include full models of all modules and zones associated with the system rather than their ID.

{
    "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"
}

Update

PUT 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

NameTypeDescription

id

string

ID of the system to update.

Request Body

NameTypeDescription

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

{
    "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"
}

Delete

DELETE 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

NameTypeDescription

id

string

ID of the system to retrieve.

Interaction

Start

POST https://example.com/api/control/systems/{id}/start

Starts all modules associated with the system.

Path Parameters

NameTypeDescription

id

string

ID of the system to start.

Stop

POST https://example.com/api/control/systems/{id}/stop

Stops all modules associated with the system.

Path Parameters

NameTypeDescription

id

string

ID of the system to stop.

Exec

POST 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

NameTypeDescription

id

string

ID of the system to execute within.a

Request Body

NameTypeDescription

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.

[]

State

GET https://example.com/api/control/systems/{id}/state

Query the state exposed by a module within the system.

Path Parameters

NameTypeDescription

id

string

ID of the system the module is in.

Query Parameters

NameTypeDescription

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.

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

Funcs

GET https://example.com/api/control/systems/{id}/funcs

Query the behaviour exposed by a module within the system.

Path Parameters

NameTypeDescription

id

string

ID of the system that the module is in.

Query Parameters

NameTypeDescription

module

string

Class of the module.

index

integer

(default 1) Index of the module.

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

Count

GET https://example.com/api/control/systems/{id}/count

Counts the instances of a driver type within a system.

Path Parameters

NameTypeDescription

id

string

ID of the system to query.

Query Parameters

NameTypeDescription

module

string

Class name of the modules to count.

{
  "count": 3
}

Types

GET https://example.com/api/control/systems/{id}/types

Query the types of modules available within a system.

Path Parameters

NameTypeDescription

id

string

ID of the system to query.

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

Last updated