*OpenAPI – General information
- Tom Polman
Configuration Article | CA-20200930-TP-27 VDG Sense | OpenAPI |  |  |
The OpenAPI, introduced in VDG Sense 2.6.1 stands for an open and self-explaining interface for the VDG software. The main goals for the OpenAPI are threefold:
One API for all parties (including TKH Security)
One API for maintenance and testing
Allowing deeper system integrations with VDG software
With the OpenAPI, integrators or Third Party developers can develop their own interfaces for VDG Sense using one or more of the microservices that run within the software. To better understand the difference with the previous scenario, see the following diagrams.
VDG Sense 2.5 situation
In VDG Sense 2.5 and lower, there was a significant closed protocol between the Video Management software and the configuration services. Trivial parts of the Video Management are only available for TKH Security applications. To allow for integrations, an API was made available, which contains a small subset of available functionalities. The API allowed limited access to the configuration through the Video Manager, and commands were finally converted to the closed protocol. This also required some conversion on VDG Sense’s back-end. Due to this, there’s necessary, but redundant, maintenance requirement for both the closed protocol and the API.
VDG Sense with OpenAPI
With the OpenAPI, these trivial parts of the VMS will become accessible through an open protocol via a modern and secure API for all involved parties, including TKH Security. This means that the all Sense client applications (native client, mobile app and web client or any other future products) will use the same API as integrators. The Video Manager is no longer used as the gateway between the configuration and the client, meaning it’s main purpose will be simplified to display and store video, and not for configuration, user management and API communications. This also allows for a deeper, or a more precise integration with VDG Server software by system integrators. For example, an integrator that only requires Events & Notifications from Sense, can communicate through the OpenAPI to receive only that information stream. But an integrator is also able to request each component and can, develop an entire standalone client application to configure VDG Sense. This also has the huge benefit that only one API needs to be maintained and tested by TKH Security.
The Open Application Interface is designed to run under highly secured conditions:
Transport
All transport regarding configuration will be send over an encrypted connection.Authentication
By fully implementing the OAuth2 standard, it is not required anymore to send passwords along with each API call.Storage
All configuration data with privacy sensitive data will be saved encrypted or hashed in a safe environment.
Transition period
The OpenAPI will not be fully implemented in VDG Sense 2.6.1, but will be introduced in a phased release. This allows TKH Security to gradually introduce new features and development methods while integrators can prepare for upcoming changes.
Release flow
VDG Sense will see a new minor version (2.6 → 2.7) every 6 months with a planned expanded functionality to the OpenAPI. A regularly maintenance update (2.6.1 → 2.6.2 etc.) will be released every 2 months in between the minor updates including beta releases to certain clients.
Micro services
VDG Sense with the OpenAPI will be divided into four microservices. These miscroservices are: Media, Configuration, Operator Functions and Events & Notifications. Each microservice will handle a small part of the software and can be used or integrated individually. In the sections below, a short description of each service will be given
Media
The media micro services allows a transparent access, both live and playback, to the video, audio and meta data (motion, VCA events, etc) over secured connections and is available in open standards like:
RTSP
WebRTC
MJPEG multipart stream
The media stream are available in various stream formats and can be requested in any stream format you’d like (codec, resolution, bandwidth etc).
Configuration
The configuration micro services contains all the main resources of a VDG Sense installation. These are the server information, added devices, users, macros etc. In VDG Sense 2.6.1, the first part of the configuration microservices are introduced in which the users are configured. Users and their configuration rights and permissions are a big central part of the configuration that combines nearly all configuration options in a single place. For example which devices the user is allowed to see, which servers the user can login to and which layouts he is allowed to open on his screen. The users can be both configured in the Web configuration and the native client.
Operator Functions
The Operator micro services is a programmatic control of operator functions like:
Selecting a specific layout
Add camera to a layout
PTZ control device
etc.
Events & Notifications
Events and Notifications created in VDG Sense will become available using open standards like WebSocket or Webhooks. This will make it easier for integrators to listen and react on incoming events/notifications generated in a VDG Sense system. This will be available on all playtforms (Web, Mobile & Native applications).
Configuration encryption
All configuration data with privacy sensitive data will be saved encrypted or hashed in a safe environment. This means that the initialization files (.ini files) can no longer be opened or modified outside of the application.
Web configurator
Starting with VDG Sense 2.6, the configuration options will be slowly migrated into a Web configuration. VDG Sense 2.6.1 will start with a few user settings, which are also still available in the native client, but eventually, the web configurator will be entirely replacing the configuration options in the native client. The native client will still be used for Live mode, including the various tools available to operators, but configuration will no longer be present.
Replication of configuration
VDG Sense uses CouchDB for the storage of configuration data. CouchDB is known for replication of data. As soon as you connect a slave server to a master server, all data will be deleted from the slave server. After this, the data will be synchronized. As a result, the slave server receives all resources that are available in the OpenAPI from the master server. All data will be available on every server, regardless of which server you add it to or request it from. As soon as you disconnect a slave server from its master, the data will be kept on the slave server so that it can continue to operate on its own.