GVOrbit Alarm REST API

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