Overview for Remote Monitoring Providers

Prerequisites

To use ACS API, you need:

  • User account for the service provider organization in ACS

  • ACS API key provided by the Avigilon Integrations team.

To request the above, contact integrations@avigilon.com. You will need to provide your Organization name and email account for the Organization administrator.

Provider should receive an email with instructions and another email with the Key.

Initial Setup

  1. When you receive an invitation email from the Avigilon Cloud Services Team, complete the registration process by providing your First Name, Last Name and a new password (see the figure).

    Note: We recommend having a dedicated e-mail created that can be shared among any developers within your organization who need to access Avigilon Cloud Services.

  2. When the registration is complete, you may sign into the ACS. Upon the first sign-in, accept the EULA.

Remote Monitoring Service Package

  1. To acquire access to Customer Organizations owned video sources, they need to grant you access to the video sources connected to their ACS sites. They do this by using the Service Package Code that you provide to them. To access your Service Package Code, navigate to the Service Packages tab on the landing page and observe the code provided for the factory generated Remote Monitoring package.

  2. For each Customer Organization you want to offer your services for

    • Provide the Code of you Remote Monitoring factory created service package.

    • Ask them to apply the code for their selected sites.

  3. When the Customer Organization applies the code, it becomes visible on the Customers list as a Pending Request (see the figure). Accept the request.

  4. Once the request has been accepted, the customer shows up on your Customers list as a regular entry.

Central Station and Agent User

For each accepted site, you can access the site's video sources via the Cloud API using the so called Agent User credentials of the Central Station.

  1. Central Station is the way that the ACS platform provides for Remote Monitoring Providers to gain access to Customer Sites for purposes of monitoring. An Agent user account is defined for each Central Station.

  2. Agent user name and password are the only credentials allowed to access Cloud API. Agent user name is not required to be any email address. Agent user name and password never expires and can not be locked by multiple authentications failures.

    Note: In order to create a Central Station follow the manual Create a Central Station

Using The Avigilon Cloud Services API

API Capabilities

Using the Cloud API, you can:

  • Authenticate in the API using your Agent User credentials

  • Retrieve a list of cameras in sites of the underlying customer organizations

  • For each camera: 

    • Get camera details.

    • Request to create either live or recorded RTSP session.

    • List PTZ presets and tours, trigger a PTZ preset and PTZ home position, start and stop a PTZ tour.

    • Take video snapshots.

REST

The Cloud API is a REST API. It adheres to the following guiding principles of REST:

  • Client-Server - By separating client concerns from server concerns, we improve the portability of clients across multiple platforms and improve scalability by simplifying server components.

  • Stateless - Each request from client to server must contain all the information necessary to understand the request. Session state is therefore kept on the client; each request is separate and unconnected.

  • Cacheable - Data is cacheable–streamlining client-server interactions.

  • Uniform Interface - REST is defined by four interface constraints needed to obtain a uniform interface: identification of resources; manipulation of resources through representations; self-descriptive messages; and hypermedia as the engine of application state (HATEOAS).

  • Layered System - The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.

HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST architectural style. HATEOAS is a complicated-sounding term for a simple idea:

A client interacts with a REST API entirely through the responses provided dynamically by the server.

The restrictions imposed by HATEOAS decouple client and server, enabling server functionality to evolve independently. A pure HATEOAS API is conceptually the same as a web browser navigating the Internet and requires no documentation. Thus, ACS API is not “pure” but does leverage the concepts wherever practical.

An ACS API client begins interacting with the API through a simple fixed URL /system and uses the resulting server-provided resource representations and links to dynamically discover available actions and access and manipulate resources. Additionally, the client does not have to hard code the URI structures for various resources; HATEOAS allows the server to make URI and resource relationship changes as the API evolves without breaking the clients.

Usage - General

Access Control

Each request to the Cloud API Gateway must be equipped with an API key - otherwise requests will be rejected. The API key has to be provided as a value of the ApiKey HTTP header. Contact Avigilon at integrations@avigilon.com to obtain your API key.

Client Interaction

An ACS API client begins interacting with the API through a simple fixed URL /system and uses the resulting server-provided MSI.VMS.System resource representations and links to dynamically discover available actions and access and manipulate resources

Version Negotiation

When a client retrieves a /system URL, it MUST request the ACS API version to work with by applying a version accept-extension [RFC 2616, Section 14.1] containing the range of versions it supports. The ACS API will select the highest version in the requested range that it supports and return this version using a version parameter on the Content-Type in the response. If the ACS API does not support any of the requested versions, it will return 501 (Not Implemented). Clients receiving a 501 (Not Implemented) SHOULD inform the user that the client is incompatible with the ACS API. If no version is requested by the client, the ACS API will return a 406 (Not Acceptable).

Notes:

  • Version negotiation is only provided for by the MSI.VMS.System resource and, once retrieved, a client is able to navigate through the link tree such that the requested version is maintained without further negotiation.

  • ACS API version(s) supported in the current release are provided in Release Notes.

Example – Supported Versions: Client (2,3,4) & Server (1,2,3)

Client Request

GET /system 
Accept: application/json; version=2-4 
...

Server Response

200
Content-Type: application/json; version=3
...
Example – Supported Versions: Client (7) & Server (5,6)

Client Request

GET /system 
Accept: application/json; version=7-7
...

Server Response

501
...

Authentication

To authenticate in the Cloud API:

  • Access /system URL

  • Using return rel/login link in the _links section, perform log in operation, providing the credentials of Agent User configured for your Central Station.

  • Upon successful login, use received cookie with all subsequent calls to the API.

  • Access /system URL again to list the available functions

List of APIs

Use this link.