openapi: 3.0.1
info:
title: GV Orbit AlarmAPI
description: >
The AlarmAPI provides access to the GV Orbit monitoring data via REST.
The monitoring
data is presented using the Common Data Model for Alarms (CDMA) model. This model provides the current state of all Grass Valley equipment, including IQ modular, Densite, Multi-Viewers etc.
This document defines the endpoints used to access this data, including input and output data types.
This is an OpenAPI 3.0 document and as such can be used to auto generate HTML documentation
along with client and service side APIs. The normative form of this document is the YAML file.
All calls are currently unencrypted using HTTP and as such usage of the API should be considered
during the architecture of the system. The AlarmAPI service has an option to switch off inbound
alarms, essentially providing a read-only access to the data.
The API supports:
* Querying of alarms
* Alarm notifications using push or pull
* Creation, update and deletion of alarms
* Automatic removal of obsolete alarms where a publisher is inactive
Within a GV Orbit system, alarms are grouped into collections based around a device (sometimes
called a Unit). Devices may be physical, such as a modular card, or virtual such as a categorized
alarm. To obtain a list of all devices use the /devices endpoint. Devices are identified by a path,
which may be a virtual Linux style file system path (typical on Densite/iControl equipment) or a
RollCall address of the form NNNN:UU:PP. The RollCall address has a logical path built in and
therefore can be resolved to a path in a network tree.
This method of identification is under review and may change to standardize the RollCall/Densite
identifiers.
Each device is likely to have multiple alarms. Once the path of the devices are known, alarms can be
obtained using the /alarms endpoint and passing the device path.
Notifications are supported using either "push" or "pull". In either case a subscription needs to be
created by the client, with an optional filter, and the server will push events to a URL
provided by the client, or a client may pull changes from the server. The server in both cases keeps
track of changes for each subscription so avoids delivering the same data multiple times. Once a
client is finished with a subscription, they should delete it to avoid consuming server resources.
However to protect against non-graceful cleanup of a client, the server will automatically delete a
subscription if it has been inactive for 60 seconds, so the requirement to call delete is not strict.
Where no data is flowing (perhaps a filter is in place), and "push" is configured, the server will send
an empty array of events to the client at least within 60 seconds to test its validity before deleting
the subscription. If the connection fails, it will be re-attempted up to 3 times before the
subscription is automatically deleted. To further ensure that subscriptions are not deleted without
the client being aware, the client should test the subscription is valid using the
GET /subscriptions endpoint. This prevents the server losing contact with the client, removing
the push subscription without the client being aware of it.
Alarms may be created in the system via the POST /alarms endpoint. Before an alarm can be
created however, the client will first need to register a publication id in the form of a GUID which
should then be injected into the 'origin' field for each alarm. The server will reject any attempt to
create an alarm without a valid publication id. An advantage of this approach is it facilitates a fire-
and-forget approach where a client can publish alarms and be assured the GV Monitoring System
will detect when that client disappears, thus cleaning up and marking that device as lost.
Note: Clients do not need to create devices as a separate stage, simply creating one alarm is enough
to have that device automatically created.
version: 1.0.0
servers:
- url: 'http://gv-orbit-server:9099/alarmapi/v1/'
paths:
/ping:
get:
summary: >-
Returns a http status code indicating whether the service is alive or
not.
description: >
Obtains an http status code indicating whether the service REST API is
alive and running.
operationId: ping
responses:
'204':
description: OK
content: {}
x-swagger-router-controller: Default
/devices:
get:
summary: Gets a list of device paths.
description: >
Returns a list of all devices paths in the Monitoring System. The path
can then be used in subsequent requests to obtain alarms for a specific
device. A single device would typically have multiple alarms associated
with it. Devices may be virtual or physical.
operationId: getDevices
responses:
'200':
description: An array of device paths
content:
application/json:
schema:
type: array
items:
type: string
example: 'A000:01:01'
'401':
description: Unauthenticated.
content: {}
x-swagger-router-controller: Default
/alarms:
get:
summary: Gets a list of the alarms for a given device.
description: >
Returns alarms for a given device. The device paths can be obtained
using the /devices endpoint. If multiple device alarms are required, multiple calls
need to be made for each device.
An alternative is to subscribe to alarm changes. When using this approach all alarms
will be delivered initially, and then subsequent updates.
operationId: getAlarms
parameters:
- name: path
in: query
description: >-
The path identifying the device for which the alarms should be obtained.
required: true
schema:
type: string
- name: name
in: query
description: >-
The name of an alarm to obtain. This field may be empty, contain a * character or
a single character wildcard ?. I.e. to return all CPU_N_TEMP alarms use CPU_*_TEMP
required: false
schema:
type: string
responses:
'200':
description: An array of alarm objects with a snapshot of the current alarms.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Alarm'
'400':
description: Bad input parameter.
content: {}
'401':
description: Unauthenticated.
content: {}
x-swagger-router-controller: Default
post:
summary: Adds or updates alarms
description: >
Adds or updates (an array of) alarms in the monitoring system.
The path and name uniquely identify the alarm and must be unused by existing alarms, or
the publication id specified in the 'origin' field must match the
existing alarm in which case it will be updated.
Alarms are added with a publication id. This should have first been
registered using the publications endpoint.
The client should populate the 'origin' field with the publication id before adding the alarms.
operationId: setAlarms
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Alarm'
required: false
responses:
'201':
description: Alarm(s) created or updated.
content: {}
'400':
description: 'Invalid input, request has been rejected.'
content: {}
'403':
description: 'Write access is disabled on the server.'
content: {}
'401':
description: Unauthenticated.
content: {}
'409':
description: >-
An existing item already exists and cannot be modified. Check the
origin is set to a valid publication id.
content: {}
x-swagger-router-controller: Default
x-codegen-request-body-name: alarms
/alarms/deletions:
post:
summary: Removes alarms from the monitoring system
description: >
Removes alarms from the monitoring system. The client should provide a list of alarms which should be removed.
A single * character may be used in the name field, in which case all alarms will be removed. The path field, identifying the device, must be specified in full.
operationId: removeAlarms
parameters:
- name: publicationId
in: query
description: The publication id of the publisher to delete
required: true
schema:
type: string
requestBody:
description: An array of alarm Ids to delete.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Id'
required: false
responses:
'204':
description: Alarm(s) deleted ok.
content: {}
'400':
description: 'invalid input, object invalid'
content: {}
'403':
description: 'Write access is disabled on the server.'
content: {}
'401':
description: Unauthenticated.
content: {}
'409':
description: >-
An existing item already exists and cannot be modified. Check the
publicationId is valid for the alarms you are attempting to delete.
content: {}
x-swagger-router-controller: Default
x-codegen-request-body-name: alarms
/publishers:
put:
summary: |
Creates an alarm publisher.
description: >
A publisher is a resource which identifies anyone creating alarms within
the GV Orbit Monitoring system using this API. When a publisher is
created this allows the publisher to publish alarms. The client must
ensure the id sent in creating the publisher matches the 'origin' field
of the CDMA alarms. This is validated by the server before the alarms
are added to the monitoring system.
It is up to the client to choose a publication Id (origin) value. A guid
is a sensible choice. If an existing ID is already present in the system,
the name is compared and if it differs, the system will return an error.
If the name matches it will return 201.
The server prevents alarm updates unless the alarm being updated has the
same publication id as the new update.
Finally, the server keeps track of publication ids for usage in order to
detect dead clients. Clients have a responsibilty for keeping
publications alive, either by publishing a change or calling the
keepalive endpoint. After {60} seconds, of having not seen a publication
id, the server will remove the alarms it created and mark any devices as
"Unit Lost".
operationId: createPublisher
requestBody:
description: >
Two fields which uniquely idenfity this publisher. The origin should
be a GUID, and the name is just some opaque information that is used
as a secondary verification to the GUID.
content:
application/json:
schema:
$ref: '#/components/schemas/Publication'
required: false
responses:
'201':
description: The publication was created.
content: {}
'403':
description: 'Write access is disabled on the server.'
content: {}
'400':
description: Bad request - missing body.
content:
application/json:
schema:
type: string
example: >-
The request was missing the publication information from the
body.
'401':
description: Unauthenticated.
content: {}
x-swagger-router-controller: Default
x-codegen-request-body-name: publication
get:
summary: Informs the server that this publisher is still valid.
description: >
Keeps the publication id alive on the server and returns status
information regarding its validity to the client. This acts as a
keep-alive for alarms created with a given publication id. Alarms are
also kept alive by any alarm updates with that publication id.
operationId: getPublisher
parameters:
- name: publicationId
in: query
description: The publication id obtained when the publisher was created.
required: true
schema:
type: string
responses:
'200':
description: The publication id is valid.
content:
application/json:
schema:
$ref: '#/components/schemas/Publication'
'401':
description: Unauthenticated.
content: {}
'404':
description: The subscription id was not found/invalid.
content: {}
x-swagger-router-controller: Default
delete:
summary: Deletes an alarm publisher.
description: >
Removes a publication from the server and delete all alarms created with
that publication id.
operationId: deletePublisher
parameters:
- name: publicationId
in: query
description: The publication id of the publisher to delete
required: true
schema:
type: string
responses:
'204':
description: The publication was deleted successfully.
content: {}
'403':
description: 'Write access is disabled on the server.'
content: {}
'404':
description: The publication was not found.
content: {}
x-swagger-router-controller: Default
/subscribers:
put:
summary: |
Creates a subscription for events.
description: >
Creates a subscription for alarm events. This endpoint returns a session
id which can then be used to request changes.
This operation returns a subscription id (a 64 character GUID) which
should be used in subsequent subscription operations, such as pull,
delete or verify.
operationId: createSubscriber
requestBody:
description: >
An array of device ids (paths) for which the client is interested.
If this array is empty, the subscriber will be delivered everything.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
required: false
responses:
'200':
description: A subscription id. This should be used in subsequent requests.
content:
application/json:
schema:
type: string
format: uuid
example: 7ce05a50-e8ec-4c1d-adfe-4677f8d22965
x-swagger-router-controller: Default
x-codegen-request-body-name: subscription
get:
summary: Tests a subscription id for validity.
description: >
Given a subscription id, returns http 200 if this is valid, http 404
otherwise. This may be used by the client to periodically detect whether
a subscription has been lost (i.e. automatically deleted), or server
restarted. If this occurs, the subscription will need to be re-created
by the client.
operationId: getSubscriber
parameters:
- name: subscriptionId
in: query
description: The subscription id obtained from the call to subscribe.
required: true
schema:
type: string
responses:
'200':
description: The subscription id is valid.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'401':
description: Unauthenticated.
content: {}
'404':
description: The subscription id was not found/invalid.
content: {}
x-swagger-router-controller: Default
delete:
summary: Deletes a subscriber.
description: >
Removes a subscription for alarm events. The server will no longer track
changes for this subscription id.
operationId: deleteSubscriber
parameters:
- name: subscriptionId
in: query
description: The subscription id of the subscriber to delete
required: true
schema:
type: string
responses:
'204':
description: The subscription was deleted successfully.
'401':
description: Unauthenticated.
content: {}
'403':
description: 'Write access is disabled on the server.'
content: {}
'404':
description: The subscription id was not found.
content: {}
x-swagger-router-controller: Default
/alarms/changes:
get:
summary: Gets all alarm changes for a subscription since the last poll.
description: >
Given a subscription id, returns a list of all the alarm changes.
Additions, deletions and update, in order, since the last request.
The server will keep track of all changes for each
subscription, so will only deliver changes that the client has not
seen before.
Likewise, if the client is not polling (perhaps processing
items) the server will track changes and deliver them immediately on the
next call to poll.
This method uses long polling technique and will block for up to 30 seconds if there is no data after which it will return http 201.
The client should then immediately re-connect for further updates.
Note: An alternative to long polling which may be more responsive is to
configure a push notification url where the server will send changes.
operationId: getAlarmChanges
parameters:
- name: subscriptionId
in: query
description: The subscription id obtained from the call to subscribe.
required: true
schema:
type: string
responses:
'200':
description: An array of alarm objects with a snapshot of the current alarms.
content:
application/json:
schema:
$ref: '#/components/schemas/Events'
'204':
description: >-
No events occurred during this poll. No data. Client may continue to
poll for new data.
content: {}
'401':
description: Unauthenticated.
content: {}
'404':
description: The subscription id was not found.
content: {}
x-swagger-router-controller: Default
components:
schemas:
Id:
required:
- name
- path
type: object
properties:
path:
type: string
description: >
Unique identifier for the device containing an alarm. For IQ devices
this will be a RollCall address. For Densite alarms this will be a
virtual Linux style folder path. Third-parties may use with either
approach. The path is used to group multiple alarms under a common
folder and is used within Orbit to show items in the network tree.
example: '11704080'
name:
type: string
description: |
The name of the alarm.
Note: The path + the name forms a unique key for the alarm.
example: POWER_USAGE
description: The unique identifier for an alarm
example:
path: '11704080'
name: POWER_USAGE
Filter:
required:
- path
type: object
properties:
path:
type: string
description: >
Unique identifier for the device containing an alarm. For IQ devices
this will be a RollCall address. For Densite alarms this will be a
virtual Linux style folder path. Third-parties may use with either
approach. The path is used to group multiple alarms under a common
folder and is used within Orbit to show items in the network tree.
example: '11704080'
description: The unique identifier for a device
example:
path: '11704080'
name: POWER_USAGE
Alarm:
required:
- id
- state
type: object
properties:
id:
$ref: '#/components/schemas/Id'
origin:
type: string
description: >
Used as a parent identifier for an alarm. Physical alarms take the
serial number of the originating device. Virtual alarms would not
use this field.
example: S00000102
state:
$ref: '#/components/schemas/State'
description: >
The alarm object provides the state of an alarm within the monitoring
system. Alarms are contained within devices (sometimes called units)
which may be virtual, or may represent physical equipment. Alarms can be
used for indicating errors, but also for logging information about
equipment. Virtual alarms may be derived from other alarms.
example:
origin: S00000102
id:
path: '11704080'
name: POWER_USAGE
state:
acked: false
ackedBy: ''
unmaskedState: ok
ackedTimestamp: ''
state: ok
masked: false
latchedState: ok
value: 84.5 LU
inverted: false
timestamp: 2020-01-28T09:12:33.001Z
State:
required:
- state
- timestamp
type: object
properties:
state:
type: string
enum: ["nostate", "ok", "warn", "caution", "fail", "text"]
description: >
The current state of the alarm.
Valid values are: "nostate", "ok", "warn", "caution", "fail" where
fail is the most severe.
example: ok
latchedState:
type: string
description: >
The worst state that this alarm has been in since a user has reset
latches. This allows glitches to be detected where an alarm briefly
errors before going green again.
example: ok
unmaskedState:
type: string
description: >
The current unmasked state of the alarm. If an alarm is masked, its
state is suppressed and the state field will go to "nostate". This
field will capture what the state would be, if the mask was not
applied.
example: ok
timestamp:
type: string
description: The timestamp when the alarm occurred.
format: date-time
example: 2020-01-28T09:12:33.001Z
value:
type: string
description: The value (or text) content of the alarm.
example: 84.5 LU
masked:
type: boolean
description: >
This flag indicates that the alarm is masked and therefore the alarm
state is suppressed.
example: false
inverted:
type: boolean
description: >
This flag indicates that the alarm is inverted. When an alarm is
inverted, ok is as fail and warn, caution and ffail states are shown
as ok.
example: false
acked:
type: boolean
description: |
True if the alarm has been acknowleged by a user.
example: false
ackedTimestamp:
type: string
description: The timestamp when the alarm was acknowleged.
format: date-time
ackedBy:
type: string
description: The name of the user (or host machine) who acknowleged the alarm.
example: ''
description: |
Captures the current state of an alarm.
example:
acked: false
ackedBy: ''
unmaskedState: ok
ackedTimestamp: ''
state: ok
masked: false
latchedState: ok
value: 84.5 LU
inverted: false
timestamp: 2020-01-28T09:12:33.001Z
Events:
type: object
properties:
items:
type: array
description: |
Provides a list of event items.
items:
$ref: '#/components/schemas/EventItem'
description: >
The events object is used when subscribing to alarm notifications. This
object list of all the events items occurring since the last read or
push. This allows multiple events to be gathered together into a single
packet.
example:
items:
- update:
origin: S00000102
id:
path: '11704080'
name: POWER_USAGE
state:
acked: false
ackedBy: ''
unmaskedState: ok
ackedTimestamp: ''
state: ok
masked: false
latchedState: ok
value: 84.5 LU
inverted: false
timestamp: 2020-01-28T09:12:33.001Z
delete:
id:
path: '11704080'
name: POWER_USAGE
- update:
origin: S00000102
id:
path: '11704080'
name: POWER_USAGE
state:
acked: false
ackedBy: ''
unmaskedState: ok
ackedTimestamp: ''
state: ok
masked: false
latchedState: ok
value: 84.5 LU
inverted: false
timestamp: 2020-01-28T09:12:33.001Z
delete:
id:
path: '11704080'
name: POWER_USAGE
EventItem:
type: object
properties:
update:
$ref: '#/components/schemas/Alarm'
delete:
required:
- id
type: object
properties:
id:
$ref: '#/components/schemas/Id'
description: >
Wraps either an alarm or an alarm id depending on whether this is an
update or delete event. Event Items will be delivered in the order they
occur within the system.
example:
update:
origin: S00000102
id:
path: '11704080'
name: POWER_USAGE
state:
acked: false
ackedBy: ''
unmaskedState: ok
ackedTimestamp: ''
state: ok
masked: false
latchedState: ok
value: 84.5 LU
inverted: false
timestamp: 2020-01-28T09:12:33.001Z
delete:
id:
path: '11704080'
name: POWER_USAGE
Subscription:
required:
- type
type: object
properties:
type:
type: string
description: >-
May be "push" or "pull" depending on how the client would like to
recieve notifications.
example: push
url:
type: string
description: >
The call-back url where the server should send events. This is used
when type is set to "push" and not required for "pull", in which
case the client is responsible for pulling changes via the
notifications/pull endpoint. The data sent to this url will be an
Events object, which then contains a list of Event Items.
example: 'http://192.168.15.2/my_app/alarm_handler'
filter:
type: array
description: >
An array of alarms to be used as a filter by the server when delivering
changes to the client. An empty array will deliver everything.
items:
$ref: '#/components/schemas/Filter'
description: |
Provides details about a new subscription.
example:
filter:
- path: 'A000:01:02'
- path: 'A000:02:03'
type: push
url: 'http://192.168.15.2/my_app/alarm_handler'
Publication:
required:
- name
type: object
properties:
origin:
type: string
description: UUID of the publisher
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description: Some name which identifies the publisher.
example: Blaze Video Processing
description: |
Provides details about a publication.
example:
origin: 123e4567-e89b-12d3-a456-426614174000
name: Blaze Video Processing
