API

Enable external programs and users to connect to the PrismUI event stream and send commands to PrismUI Objects.

Introduction

The PrismUI API is a module installed alongside PrismUI Runtime. It allows external applications to connect and interact with PrismUI. This includes sending commands, querying the system for live states, and listening to the live event stream.

Installation

In order to use the PrismUI API, the API service must be installed and running as a Windows service on the Runtime Workstation you would like to expose to the API.

Setup

The Workstation must be configured to use the API before it is available to be used. This configuration option is found in Project Settings > API. Check to enable each Workstation you want to have the API available. In Service Settings you can change the Username and Password that is used to authenticate with the API when Security is enabled.

Use

To use the API go to the docs URL. Make sure to replace {machinename} with the IP address or DNS name of the computer on which the API service is running.

Unsecured connection:

http://{machinename}:8080/docs

Secured connection:

https://{machinename}:8612/docs

The docs URL is a HTML UI view that contains the documentation on how to use the API. There are features in this page that are available to test the API when Runtime is running.

Unsecured connection:

http://{machinename}:8080/api

Secured connection:

https://{machinename}:8612/api

The /api URL is the main URL root for all API commands.

Unsecured connection:

http://{machinename}:8080/api/events

Secured connection:

https://{machinename}:8612/api/events

The events URL is a SignalR Hub as outlined in the docs. When opened, this end point will stream Runtime states of integrated systems and assets to the client.

Notes

  • API Token based security can be enabled and disabled with the applicationsettings.json file. This uses the Authorization Header field with the token parameter.
  • HTTP access can be disabled with the applicationsettings.json file. Setting UseHTTPS to true will force an HTTPS connection.
    Note: The SSL certificate installed by default is self-signed. The certificate included in the API service installation expires 1000 years after installation. Using this certificate may result in warning when accessing the API. These warnings can be dismissed in order to use the certificate. If desired, you can replace it with a trusted certificate.
  • HTTPS port can be modified with the applicationsettings.json file.
  • When the Runtime is not running, the API service will return a 503 status code.
  • When the Runtime reboots, the API cache of item state will be cleared and recreated.