Capability Concepts

The API Gateway provides access to functionality to API users by allowing those users to subscribe to, and hence receive messages, and by allowing users to send messages. In order to perform some role that involves using the API, an API user needs to receive (subscribe to) and/or send (_publish_) messages of one or more types. Similarly, logical units of functionality exposed via the API may involve the use of more than one message type.

A logical unit of functionality is exposed as a Capability. The API itself is not concerned with user Roles beyond assuming that the set of API functions required by a user Role can be expressed as a set of Capabilities.

A given Capability provides the ability to send 0 or more message types and to receive (subscribe to) 0 or more message types. Obviously a capability must provide the ability to send at least 1 message type or receive at least one message type to be useful.

The mapping from a capability to a set of messages that an API user with that capability can send (publish_) is independent of such mappings for other capabilities - more than one capability may convey the right to send (_publish_) and/or receive (_subscribe to) a given message.

STOMP Destination Ownership

API users that are granted capability to publish are implicitly granted ownership of (the right to send to) particular STOMP destinations that represent instances of the messages they publish. An API user must only publish to a destination that it owns (generally by including its identity as part of the _destination_).

Capabilities Provided by API

Capabilities are grouped into families only for ease of description and organisation. The system does not internally group capabilities together in any way.

Live Capability Family

The Live capability family grants access to subscribe to/receive a set of messages reflecting the current live status of EGMs. This is conceptually similar to the capability provided to a system that connects to an X EGM port other than port 1 and so is able to see the live state of an EGM as a series of SDB, PDB etc messages reporting state of the EGM but not to in any way change/control the state of the EGM.

It is expected that the Live capability family will be used by various roles ranging from very basic data collection (which may need only this capability) to systems that need live data as part of a more complex and interactive roles, such as running a jackpot.

Live-EGM Capability

The Live-EGM capability is most directly analogous to receive-only connection to an X Series EGM data port. It provides access to a live feed of meter and status information about EGMs. It does not provide any send capability.

MAX Capability Family

The MAX capabilities are used to delineate particular functions of the MAXsys system. The individual capability descriptions reflect this. Note that MAX capabilites are not granted to other API users and are described here only to show how MAX interacts with the API and so makes MAX provided services and data available to users with other capabilites.

MAX-EGMMonitoring

The MAX-EGMMonitoring capability is restricted to those MAXsys components that directly collect data (meters, status, detected configuration) from EGMs and provide it to other components of MAXsys and to other API users. It grants the ability to publish messages that report current EGM state and changes in EGM state. Often EGM control actions result in a change in EGM state that is reflected / published using the EGMMonitoring capability, but EGMMonitoring does not include publication of any messages that are used as an integral part of EGM control transactions, as opposed to passive monitoring of EGM state changes arising from them.

MAX-EGMControl

This capability is restricted to those MAXsys components that use EGM protocols to control the EGM in some way, when requested to do so by other components, or requested to do so from the EGM. Often EGM control involves 2-way communication. The capability grants the ability to publish messages that are needed in such an interaction and flow from the EGM to other components as well as to subscribe to message that come from other components to initiate or progress the interaction with the EGM.

It does not grant the ability to initiate or progress the overall EGM control transaction without the involvement of other components, as it does not grant the right to publish messages that are expected to come from other components/API users as part of the transaction.

MAX-Monitor

This capability is used by MAXsys and/or grants API users the ability to collect / log messages for monitoring purposes. As such it grants only the right to subscribe to messages, not to publish them. Messages subscribed to are examined by MAXsys business logic to determine if they need to be collected/preserved by the CMS. This includes such functions as collecting meter readings as well as collecting logs of transactions such as ECTs performed.

MAX-Config

This capability is used by MAXsys to publish the desired/authorised configuration of EGMs. It grants the right to publish the configuration for use by other components that use if for reference or to actively check, verify, or set EGM configuration. It does not grant the right to publish any detected/actual configuration information.