Systems

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

Systems

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

GET 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.

200 A list of systems matching the search criteria.

{
    "total": 3,
    "results": [
        {
            "edge_id": "edge-QC03B3OM",
            "name": "Room 1",
            "description": null,
            "email": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
            "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

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

200

{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further cotnext",
    "email": "[email protected]",
    "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

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.

200

{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further context",
    "email": "[email protected]",
    "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

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

200

{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further context",
    "email": "[email protected]",
    "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"
}

409 The specified version does not match the current system version.

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

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

200

Interaction

Start

POST 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.

200

Stop

POST 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.

200

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

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.

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.

[]

State

GET 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.

200

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

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.

200

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

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.

200

{
  "count": 3
}

Types

GET 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.

200

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