class PlaceOS::APIWrapper

Overview

Low-level wrapper for the PlaceOS API.

Each method maps one-to-one with an API endpoint. All invocations will either provide a type-safe response object, or raise an PlaceOS::API::Error.

It's possible to use this class directly if you require the extra flexibility, however in most cases the abstractions provided by the higher-level PlaceOS::Client may be the better choice.

Included Modules

Defined in:

placeos/api_wrapper.cr
placeos/api_wrapper/auth.cr
placeos/api_wrapper/modules/discovery.cr
placeos/api_wrapper/modules/interaction.cr
placeos/api_wrapper/modules/management.cr
placeos/api_wrapper/settings.cr
placeos/api_wrapper/systems/discovery.cr
placeos/api_wrapper/systems/interaction.cr
placeos/api_wrapper/systems/management.cr
placeos/api_wrapper/zones/discovery.cr
placeos/api_wrapper/zones/management.cr

Constructors

Instance Method Summary

Macro Summary

Constructor Detail

def self.new(base_url) #

[View source]

Instance Method Detail

def auth=(token_provider : OAuth2::AccessToken | OAuth2::Session) #

Sets the authentication used by the API client.

All client instances must be authenticated prior to interaction with protected endpoints.


[View source]
def authority #

Gets the authority metadata for the attached instance.


[View source]
def before_request(*args, **options) #

[View source]
def before_request(*args, **options, &) #

[View source]
def connect_timeout=(arg) #

[View source]
def count(id : String, mod : String) #

Gets the number of mod instances available in system id.


[View source]
def create_module(dependency_id : String, edge_id : String, control_system_id : String | Nil = nil, ip : String | Nil = nil, udp : Bool | Nil = nil, port : Int | Nil = nil, makebreak : Bool | Nil = nil, uri : String | Nil = nil, custom_name : String | Nil = nil, settings : Settings | Nil = nil, notes : String | Nil = nil, ignore_connected : Bool | Nil = nil, ignore_startstop : Bool | Nil = nil) #

Creates a new module.


[View source]
def create_system(name : String, zones : Array(String), edge_id : String | Nil = nil, description : String | Nil = nil, email : String | Nil = nil, capacity : Int | Nil = nil, bookable : Bool | Nil = nil, installed_ui_devices : Int | Nil = nil, modules : Array(String) | Nil = nil, settings : Settings | Nil = nil, support_url : String | Nil = nil) #

Creates a new system.

Systems must be given a unique name within the PlaceOS instance they are running from. Additionally, a system must be a member of at least one zone. All other attributes are optional at the time of creation.


[View source]
def create_zone(name : String, description : String | Nil = nil, tags : String | Nil = nil, settings : Settings | Nil = nil, triggers : Array(String) | Nil = nil) #

Creates a new zone.


[View source]
def delete_module(id : String) #

Removes a module.


[View source]
def delete_system(id : String) #

Removes a system.

This will also stop, and remove any modules that do not belong to other systems.


[View source]
def delete_zone(id : String) #

Removes a zone.


[View source]
def exec(id : String, mod : String, method : String, index : Int = 1, *args : Array(JSON::Any::Type)) #

Executes a behaviour exposed by a module within the passed system id.


[View source]
def funcs(id : String, mod : String, index : Int = 1) #

Queries the behaviour exposed by a module within system id.


[View source]
def ping(id : String) #

Performs a connectivity check with the associated device or service.


[View source]
def read_timeout=(arg) #

[View source]
def retrieve_module(id : String) #

Retrieves all metadata associated with a module.


[View source]
def retrieve_system(id : String) #

Retrieves all metadata associated with a system.


[View source]
def retrieve_zone(id : String) #

Retrieves all metadata associated with a zone.


[View source]
def search_modules(q : String | Nil = nil, limit : Int = 20, offset : Int = 0, system_id : String | Nil = nil, dependency_id : String | Nil = nil) #

List or search for modules.

Results maybe filtered by specifying a query - q - to search across module attributes. A small query language is supported within this:

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

Up to limit systems will be returned, with a paging based on offset.

Results my also also be limited to those associated with a specific system_id, that are instances of a dependency_id, or any combination of these.


[View source]
def search_systems(q : String | Nil = nil, limit : Int = 20, offset : Int = 0) #

List or search for systems.

Results maybe filtered by specifying a query - q - to search across system attributes. A small query language is supported within this:

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

Up to limit systems will be returned, with a paging based on offset.


[View source]
def search_zones(q : String | Nil = nil, limit : Int = 20, offset : Int = 0, tags : String | Nil = nil) #

List or search for zones.

Results maybe filtered by specifying a query - q - to search across module attributes. A small query language is supported within this:

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

Up to limit zones will be returned, with a paging based on offset.

Results my also also be limited to those associated with specific tags.


[View source]
def start_module(id : String) #

Starts a module.


[View source]
def start_system(id : String) #

Start all modules within a system.


[View source]
def state(id : String, mod : String, index : Int = 1, lookup : String | Nil = nil) #

Queries the state exposed by a module within the passed system id.


[View source]
def state(id : String, lookup : String | Nil = nil) #

Queries the state exposed by a module.


[View source]
def stop_module(id : String) #

Stops a module.


[View source]
def stop_system(id : String) #

Stops all modules within a system.


[View source]
def types(id : String) #

Queries the types of modules available in system id.


[View source]
def update_module(id : String, edge_id : String | Nil = nil, control_system_id : String | Nil = nil, ip : String | Nil = nil, udp : Bool | Nil = nil, port : Int | Nil = nil, makebreak : Bool | Nil = nil, uri : String | Nil = nil, custom_name : String | Nil = nil, settings : Settings | Nil = nil, notes : String | Nil = nil, ignore_connected : Bool | Nil = nil, ignore_startstop : Bool | Nil = nil) #

Updates module attributes or configuration.


[View source]
def update_system(id : String, version : Int, name : String | Nil = nil, zones : Array(String) | Nil = nil, edge_id : String | Nil = nil, description : String | Nil = nil, email : String | Nil = nil, capacity : Int | Nil = nil, bookable : Bool | Nil = nil, installed_ui_devices : Int | Nil = nil, modules : Array(String) | Nil = nil, settings : Settings | Nil = nil, support_url : String | Nil = nil) #

Requests a change to an existing system.

In addition to specifying the ID of the system to update, you must reference the the current system metadata version for the update to be allowed. This must match the current version attribute of the system and will be incrememented following a successful update.


[View source]
def update_zone(id : String, name : String | Nil = nil, description : String | Nil = nil, tags : String | Nil = nil, settings : Settings | Nil = nil, triggers : Array(String) | Nil = nil) #

Updates zone attributes or configuration.


[View source]

Macro Detail

macro delete(path, params = nil, headers = nil, body = nil, as model = nil) #

Executes a DELETE request on the client connection.

The response status will be automatically checked and a PlaceOS::Client::Error raised if unsuccessful.

Macro expansion allows this to obtain context from a surround method and use method arguments to build an appropriate request structure. Pass from_args to to either params or body for the magic to happen. Alternatively, you may specify a NamedTuple for the contents of either of these.

Us as to specify a JSON parse-able model that the response should be piped into. If unspecified a JSON::Any will be returned.


[View source]
macro get(path, params = nil, headers = nil, body = nil, as model = nil) #

Executes a GET request on the client connection.

The response status will be automatically checked and a PlaceOS::Client::Error raised if unsuccessful.

Macro expansion allows this to obtain context from a surround method and use method arguments to build an appropriate request structure. Pass from_args to to either params or body for the magic to happen. Alternatively, you may specify a NamedTuple for the contents of either of these.

Us as to specify a JSON parse-able model that the response should be piped into. If unspecified a JSON::Any will be returned.


[View source]
macro head(path, params = nil, headers = nil, body = nil, as model = nil) #

Executes a HEAD request on the client connection.

The response status will be automatically checked and a PlaceOS::Client::Error raised if unsuccessful.

Macro expansion allows this to obtain context from a surround method and use method arguments to build an appropriate request structure. Pass from_args to to either params or body for the magic to happen. Alternatively, you may specify a NamedTuple for the contents of either of these.

Us as to specify a JSON parse-able model that the response should be piped into. If unspecified a JSON::Any will be returned.


[View source]
macro options(path, params = nil, headers = nil, body = nil, as model = nil) #

Executes a OPTIONS request on the client connection.

The response status will be automatically checked and a PlaceOS::Client::Error raised if unsuccessful.

Macro expansion allows this to obtain context from a surround method and use method arguments to build an appropriate request structure. Pass from_args to to either params or body for the magic to happen. Alternatively, you may specify a NamedTuple for the contents of either of these.

Us as to specify a JSON parse-able model that the response should be piped into. If unspecified a JSON::Any will be returned.


[View source]
macro patch(path, params = nil, headers = nil, body = nil, as model = nil) #

Executes a PATCH request on the client connection.

The response status will be automatically checked and a PlaceOS::Client::Error raised if unsuccessful.

Macro expansion allows this to obtain context from a surround method and use method arguments to build an appropriate request structure. Pass from_args to to either params or body for the magic to happen. Alternatively, you may specify a NamedTuple for the contents of either of these.

Us as to specify a JSON parse-able model that the response should be piped into. If unspecified a JSON::Any will be returned.


[View source]
macro post(path, params = nil, headers = nil, body = nil, as model = nil) #

Executes a POST request on the client connection.

The response status will be automatically checked and a PlaceOS::Client::Error raised if unsuccessful.

Macro expansion allows this to obtain context from a surround method and use method arguments to build an appropriate request structure. Pass from_args to to either params or body for the magic to happen. Alternatively, you may specify a NamedTuple for the contents of either of these.

Us as to specify a JSON parse-able model that the response should be piped into. If unspecified a JSON::Any will be returned.


[View source]
macro put(path, params = nil, headers = nil, body = nil, as model = nil) #

Executes a PUT request on the client connection.

The response status will be automatically checked and a PlaceOS::Client::Error raised if unsuccessful.

Macro expansion allows this to obtain context from a surround method and use method arguments to build an appropriate request structure. Pass from_args to to either params or body for the magic to happen. Alternatively, you may specify a NamedTuple for the contents of either of these.

Us as to specify a JSON parse-able model that the response should be piped into. If unspecified a JSON::Any will be returned.


[View source]