External APIs are a vital element of a Software-as-a-Service product. Highlight's Application Programming Interface enables you to automate your service delivery.
Our API is initially focused on the creation of and updates to bearer watches.
Future releases may include user management, working with other watch types, and interacting with other features like reporting, alerting, containers, and service tiles.
Contact us for assistance acquiring and using the API or to access technical documentation.
The Highlight API allows you to interact with your Highlight service programmatically from your organisation’s service layer or applications.
This release of the API provides facilities to add a new device to be monitored in Highlight (a “watch”), search for a watch, and update its properties.
Some common use cases for the API include:
- Reconcile a device in your estate against Highlight, allowing you to find the corresponding watch if it has previously been added to Highlight
- Query the current configuration of a device watch
- Update a device watch, for instance changing the IP address, bandwidth, or interface information
- Create a new watch for a circuit or device recently added to your estate
The production API environment provides the following safeguards:
- In Highlight’s multi-tenant environment, each access key provides access only to the client’s own data, at a customer or partner level, ensuring data privacy
- Throttling of API requests to ensure that other users on the platform are not adversely affected by large-scale API activity
- Logging of API activity to allow Highlight operational and development staff to understand usage of the API, providing information to support further development of the API.
Highlight API authentication leverages Highlight as an identity provider, so that the credentials you use to login to Highlight will also work with the API.
An endpoint is provided to allow you to use these Highlight credentials to obtain an access token to be used with future requests.
All changes to Highlight using this token will be made on behalf of the user whose credentials were used to obtain it and logged against that user.
There are a few caveats:
- The user account used needs to have certain permissions set to allow the creation of folders, location, watches, and staging (Manage folders/locations, Edit watches, etc.)
- The API feature also must be enabled for your organisation
The API provides a REST interface for accessing watch records.
Each watch is accessed via the API using its own unique ID.
Once acquired, this ID should be added to your system with the information describing that device. Using this ID when calling the API in future allows fast access to these Highlight resources from your system when querying or updating the watch information using the API.
A watch’s data is returned as a JSON object (formatted text that is human readable and readily understood).
JSON objects are used to update and create watches. Searches and requests for a watch's details are a little more straight forward and only require a URL
Contact us for the API technical document for more details of these objects and how to use them.
The Highlight API will work with your current version of Highlight (from 8.2 onwards). New versions of our API and any deprecation of our API features will be managed in a controlled manner to ensure sufficient time to update and/or change any integration code as required.