Systems

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

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

https://aca.example.com/api/control/systems
Direct queries to the systems endpoint list, or search for existing systems.
Request
Response
Query Parameters
q
optional
string
A search query for the system metadata.
limit
optional
integer
Max results to return (default 20).
offset
optional
integer
The offset within the result set.
zone_id
optional
string
Limit to systems within this zone.
module_id
optional
string
Limit to systems that contain this module.
200: OK
A list of systems matching the search criteria.
{
"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

post
Create

https://aca.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
Response
Body Parameters
name
required
string
zones
required
array
edge_id
optional
string
description
optional
string
email
optional
string
capacity
optional
integer
bookable
optional
boolean
installed_ui_devices
optional
integer
modules
optional
string
settings
optional
string
support_url
optional
string
200: OK
{
"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://aca.example.com/foo",
"id": "sys-rJQQlR4Cn7"
}

get
Retrieve

https://aca.example/com/api/control/systems/{id}
Retrieve all metadata associated with the system.
Request
Response
Path Parameters
id
required
string
ID of the system to retrieve.
Query Parameters
complete
optional
boolean
Include full models of all modules and zones associated with the system rather than their ID.
200: OK
{
"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://aca.example.com/foo",
"version": 3,
"id": "sys-rJQQlR4Cn7"
}

put
Update

https://aca.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.
Request
Response
Path Parameters
id
required
string
ID of the system to update.
Body Parameters
version
required
integer
The system metadata version. This must match the current version and increments following each successful update.
name
optional
string
description
optional
string
email
optional
string
capacity
optional
integer
bookable
optional
boolean
installed_ui_devices
optional
integer
zones
optional
array
modules
optional
string
settings
optional
string
support_url
optional
string
200: OK
{
"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://aca.example.com/foo",
"id": "sys-rJQQlR4Cn7"
}
409: Conflict
The specified version does not match the current system version.

delete
Delete

https://aca.example.com/api/control/systems/{id}
Removes a system. This will stop, and remove any modules that are not associated with other systems.
Request
Response
Path Parameters
id
required
string
ID of the system to retrieve.
200: OK

Interaction

post
Start

https://aca.example.com/api/control/systems/{id}/start
Starts all modules associated with the system.
Request
Response
Path Parameters
id
required
string
ID of the system to start.
200: OK

post
Stop

https://aca.example.com/api/control/systems/{id}/stop
Stops all modules associated with the system.
Request
Response
Path Parameters
id
required
string
ID of the system to stop.
200: OK

post
Exec

https://aca.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.
Request
Response
Path Parameters
id
required
string
ID of the system to execute within.a
Body Parameters
module
required
string
Class name of the module. i.e. `Display`, `Bookings` etc
index
optional
integer
(default 1) Module index in the system.
method
required
string
The name of the method to execute.
args
optional
array
Method arguments.
200: OK
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.
[]

get
State

https://aca.example.com/api/control/systems/{id}/state
Query the state exposed by a module within the system.
Request
Response
Path Parameters
id
required
string
ID of the system the module is in.
Query Parameters
module
required
string
Class name of the module.
index
optional
integer
(default 1) Index of the module.
lookup
optional
string
A status key of interest. If included, the response filters to this value.
200: OK
{
"foo": "abc",
"bar": 42
}

get
Funcs

https://aca.example.com/api/control/systems/{id}/funcs
Query the behaviour exposed by a module within the system.
Request
Response
Path Parameters
id
required
string
ID of the system that the module is in.
Query Parameters
module
required
string
Class of the module.
index
optional
integer
(default 1) Index of the module.
200: OK
{
"function_name": {
"arity": 1,
"params": [
"string"
]
}
}

get
Count

https://aca.example.com/api/control/systems/{id}/count
Counts the instances of a driver type within a system.
Request
Response
Path Parameters
id
required
string
ID of the system to query.
Query Parameters
module
required
string
Class name of the modules to count.
200: OK
{
"count": 3
}

get
Types

https://aca.example.com/api/control/systems/{id}/types
Query the types of modules available within a system.
Request
Response
Path Parameters
id
required
string
ID of the system to query.
200: OK
{
"Booking": 1,
"Display": 2,
"VidConf": 1
}