Network Pairing API

Overview

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

warning

This API is in BETA stage. The API is provided for testing purposes and is subject to backward-incompatible changes, including modifications to functionality, behavior, and availability. You shouldn't use it in a production environment.

Description

Configuring and managing Network Pairing (edge-to-edge) functionalities. A Network Pairing allows the pairing device to connect to and use functionalities on a remote paired device.

The VAPIX Network Pairing API makes it possible to configure connections with remote devices, making it possible to extend the functionality of the primary device.

warning

This API includes sending sensitive data over the network and should only be used over a secured channel.

Plugins

Network Pairing uses a plugin system, allowing different models to exclude features not needed on the units. Therefore, API consumers must check whether or not a plugin is supported before attempting to access its functionality. This is done by sending a GET request to the property networkpairing.v1.plugins/<plugin_name>_supported.

For example, to check if the siren light plugin is supported, send the following request:

GET /config/rest/networkpairing/v1/plugins/siren_light_supported HTTP/1.1
Host: my-device
Content-Type: application/json
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": true
}

Use Cases

Manage pairings

Pairings are located in the networkpairing.v1.pairings collection which can be queried to configure connections to remote devices. The expected users of the API are video management systems (VMS) or web UI clients.

Add a pairing

New pairings can be configured by sending a POST request to networkpairing.v1.pairings. The request body must contain the address to the remote device, a username to the remote device, as well as the password for said user. The password can be updated but never read after a pairing has been created.

warning

All communication between the devices will be encrypted. To ensure that no unauthorized actor can impersonate a remote device, the remote device's certificate common name (CN) must be provided if it differs from the address used to connect to the device. The CN can be located at System > Security > [Certificate name] > Certificate information > Issued to > Common name (CN) in the remote device's web GUI, ex: axis-12345abcd67e-eccp256-1.

For example, to add a new pairing, send the following request:

POST /config/rest/networkpairing/v1beta/pairings HTTP/1.1
Host: my-device
Content-Type: application/json

{
    "data": {
        "address": "192.168.0.2",
        "certificate_common_name": "axis-12345abcd67e-eccp256-1",
        "description": "Device in hallway with analytics turned on.",
        "nice_name": "HallwayAnalytics",
        "password": "password",
        "username": "user"
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "address": "192.168.0.2",
        "features": [
            {
                "category": "SirenLight",
                "capabilities": [
                    {
                        "enabled": true,
                        "name": "Actions"
                    }
                ]
            }
        ],
        "certificate_common_name": "axis-12345abcd67e-eccp256-1",
        "description": "Device in hallway with analytics turned on.",
        "id": "1",
        "model_name": "AXIS D4100-E",
        "nice_name": "HallwayAnalytics",
        "username": "User",
        "connection_status": "connected"
    }
}

Edit a pairing

Existing pairings can be edited by sending a PATCH request to a pairing's individual properties.

For example, to update the certificate common name for a pairing with ID 1:

PATCH /config/rest/networkpairing/v1beta/pairings/1/certificate_common_name HTTP/1.1
Host: my-device
Content-Type: application/json

{
    "data": "axis-12345abcd67e-rsa2048-1"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Remove a pairing

Existing pairings can be removed by sending a DELETE request to an entry in the collection

For example, to remove the pairing with ID 1:

DELETE /config/rest/networkpairing/v1beta/pairings/1 HTTP/1.1
Host: my-device
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

List all pairings

Existing pairings can be listed by sending a GET request to the collection

Example request:

GET /config/rest/networkpairing/v1beta/pairings HTTP/1.1
Host: my-device
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "address": "192.168.0.2",
            "features": [
                {
                    "category": "SirenLight",
                    "capabilities": [
                        {
                            "enabled": true,
                            "name": "Actions"
                        }
                    ]
                }
            ],
            "certificate_common_name": "axis-12345abcd67e-eccp256-1",
            "description": "Device in hallway with analytics turned on.",
            "id": "1",
            "model_name": "AXIS D4100-E",
            "nice_name": "HallwayAnalytics",
            "username": "User",
            "connection_status": "disconnected"
        }
    ]
}

Get capabilities provided by a pairing

To list what functionality is provided by a given pairing, send a GET request to the pairing's feature collection.

For example, to get the features of a pairing with ID 1:

GET /config/rest/networkpairing/v1beta/pairings/1/features HTTP/1.1
Host: my-device
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "category": "SirenLight",
            "capabilities": [
                {
                    "enabled": true,
                    "name": "Actions"
                }
            ]
        }
    ]
}

Toggle functionality on existing pairing

When creating a new pairing, all available features will be enabled. To disable or reenable a functionality from a paired device, send a PATCH request to the enabled property for that capability.

warning

Toggling a feature won't affect the remote device, only whether or not the feature is usable on the host.

For example, to disable the Actions capability of the SirenLight feature for a pairing with ID 1:

PATCH /config/rest/networkpairing/v1beta/pairings/1/features/SirenLight/capabilities/Actions/enabled HTTP/1.1
Host: my-device
Content-Type: application/json

{
    "data": false
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Siren and Light Plugin

The siren_light plugin allows devices to use remote siren units, such as the AXIS D4100-E, as receivers for event actions. For example, by triggering a deterring sound and light on the remote device if motion is detected by the host during nighttime.

List all available profiles on remote device

A list of profiles that can be stopped or started on a paired device, send a GET request to networkpairing.v1.plugins.siren_light.profiles.{pairingID}.

For example, to list all profiles for a pairing with ID 1:

GET /config/rest/networkpairing/v1beta/plugins/siren_light/profiles/1 HTTP/1.1
Host: my-device
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "names": [
            "Loud noise",
            "Police sirens"
        ],
        "pairing": "1"
    }
}

Get capabilities of paired device

The supported capabilities of the remote device can be retrieved by sending a GET request to networkpairing.v1.plugins.siren_light.features.{pairingID}. The data will contain an array with one or both of "siren" and "light", based on what type of the device the pairing has been made to.

For example, to get the capabilities of a pairing with ID 1:

GET /config/rest/networkpairing/v1beta/plugins/siren_light/features/1 HTTP/1.1
Host: my-device
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "supported": [
            "siren",
            "light"
        ],
        "pairing": "1"
    }
}

API Definition

Structure

networkpairing.v1 (Root Entity)

Entities

id

Description: Configured pairings

Type: Collection (Key Property: id)
Operations
- Get
- Add (Permissions: admin)
  - Required properties: address, password, username
  - Optional properties: certificate_common_name, description, nice_name

Properties

address

Description: The network address of the remote device. Must be a FQDN DNS name, an IPv4 address (dotted quad notation), or an IPv6 address.
Datatype: string
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

certificate_common_name

Description: Remote device server certificate common name.
Datatype: string
Operations
- Get (Permissions: admin)
- Set (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

connection_status

Description: Connectivity status of the remote device.
Datatype: ConnectionStatus
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

description

Description: Description of the pairing.
Datatype: PairingDescription
Operations
- Get (Permissions: admin)
- Set (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

id

Description: The pairing identifier.
Datatype: PairingID
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

model_name

Description: The detected model name of the remote device
Datatype: string
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

nice_name

Description: Short, user friendly, name of a pairing.
Datatype: PairingNiceName
Operations
- Get (Permissions: admin)
- Set (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

password

Description: The password of the user account on the remote device to use when accessing it.
Datatype: string
Operations
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

username

Description: The name of the user account on the remote device to use when accessing it.
Datatype: string
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Actions

This entity has no actions.

features

Description: Available capabilities
Type: Collection (Key Property: category)
Operations
- Get
Attributes
- Dynamic Support: No

Properties

features_category

Description: The capability category name
Datatype: string
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Actions

This entity has no actions.

features_capabilities

Description: Available capabilities
Type: Collection (Key Property: name)
Operations
- Get
Attributes
- Dynamic Support: No

Properties

enabled

Description: The capability is administratively enabled
Datatype: boolean
Operations
- Get (Permissions: admin)
- Set (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

name

Description: Name of a pairing capability.
Datatype: string
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Actions

This entity has no actions.

networkpairing.v1.plugins

Description: Plugins loaded on the device
Type: Singleton
Operations
- Get
Attributes
- Dynamic Support: No

Properties

siren_light_supported

Description:
Datatype: boolean
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Actions

This entity has no actions.

networkpairing.v1.plugins.siren_light

Description: SirenLight plugin
Type: Singleton
Operations
- Get
Attributes
- Dynamic Support: Yes

Properties

This entity has no properties.

Actions

This entity has no actions.

capabilities

Path: /networkpairing/v1beta/plugins/siren_light/capabilities
Description: Capabilities on remote devices
Type: Collection (Key Property: pairing)
Operations
- Get
Attributes
- Dynamic Support: No

Properties

pairing_id

Description: Unique identifier of a pairing.
Datatype: PairingID
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Actions

This entity has no actions.

supported

Path: /networkpairing/v1beta/plugins/siren_light/capabilities
Description: Array containing string representations of capabilities supported by the device
Datatype: SLCapabilities
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Actions

This entity has no actions.

profiles

Path: /networkpairing/v1beta/plugins/siren_light/profiles
Description: The SirenLight profiles available on paired devices
Type: Collection (Key Property: pairing)
Operations
- Get
Attributes
- Dynamic Support: No

Properties

names

Description: Profile names
Datatype: SLProfileNames
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

pairing

Description: The pairing providing the profiles
Datatype: PairingID
Operations
- Get (Permissions: admin)
Attributes
- Nullable: No
- Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Actions

This entity has no actions.

Data Types

ConnectionStatus

Description: Status of the connection between the host and remote device.
Datatype: string
Enum Values: "connected", "disconnected", "error_unknown", "error_authentication", "error_certificate"

PairingDescription

Description: Description of a network pairing.
Datatype: string
Maximum Length: 200

PairingID

Description: Assigned pairing id.
Datatype: string
Pattern:^[1-9][0-9]*$

PairingNiceName

Description: Short, user friendly, name of a pairing.
Datatype: string
Maximum Length: 50

SLCapability

Description: SirenLight capability.
Datatype: string
Enum Values: "siren", "light"

SLProfileNames

Description: Profile name.
Datatype: array
Null Value: No

Overview​

Description​

Plugins​

Use Cases​

Manage pairings​

Add a pairing​

Edit a pairing​

Remove a pairing​

List all pairings​

Get capabilities provided by a pairing​

Toggle functionality on existing pairing​

Siren and Light Plugin​

List all available profiles on remote device​

Get capabilities of paired device​

API Definition​

Structure​

Entities​

id​

Properties​

address​

certificate_common_name​

connection_status​

description​

id​

model_name​

nice_name​

password​

username​

Actions​

features​

Properties​

features_category​

Actions​

features_capabilities​

Properties​

enabled​

name​

Actions​

networkpairing.v1.plugins​

Properties​

siren_light_supported​

Actions​

networkpairing.v1.plugins.siren_light​

Properties​

Actions​

capabilities​

Properties​

pairing_id​

Actions​

supported​

Actions​

profiles​

Properties​

names​

pairing​

Actions​

Data Types​

ConnectionStatus​

PairingDescription​

PairingID​

PairingNiceName​

SLCapability​

SLProfileNames​

Overview

Description

Plugins

Use Cases

Manage pairings

Add a pairing

Edit a pairing

Remove a pairing

List all pairings

Get capabilities provided by a pairing

Toggle functionality on existing pairing

Siren and Light Plugin

List all available profiles on remote device

Get capabilities of paired device

API Definition

Structure

Entities

id

Properties

address

certificate_common_name

connection_status

description

id

model_name

nice_name

password

username

Actions

features

Properties

features_category

Actions

features_capabilities

Properties

enabled

name

Actions

networkpairing.v1.plugins

Properties

siren_light_supported

Actions

networkpairing.v1.plugins.siren_light

Properties

Actions

capabilities

Properties

pairing_id

Actions

supported

Actions

profiles

Properties

names

pairing

Actions

Data Types

ConnectionStatus

PairingDescription

PairingID

PairingNiceName

SLCapability

SLProfileNames