Body worn integration API

The Body worn integration API makes it possible to integrate a third-party application as a content destination (CD) to the Body worn system (BWS). The application that implements the API will operate as the server, while the BWS will be the client that calls the API. The API itself is HTTPS-based and communication with the application is protected by certificates, which needs to be configured before the API can be used.

Terminology

Overview

API endpoints

In order to set up a connection, as well as the Body worn system, a JSON connection file needs to be created for the Body worn manager (BWM), which is the web based management application for the BWS. The connection file should contain all configurations that are required to connect to the content destination, including installation-specific settings such as encryption and the supported container format for the content destination.

Every application that implements the Body worn integration API must be able to provide this file, but it can also be made from the ground up.

Please note that when a system is configured for the first time, it must also be assigned a System ID. This ID is stored on the BWS and set on the content destination. It also makes it possible to check that the system is communicating with the expected endpoint.

Setup procedure

The connection file is a JSON file with attribute names, value types and lengths, as shown in the template below. The maximum size of a connection file should always be smaller than 64 kB.

{
  "ConnectionFileVersion": "1.0",
  "SiteName": "<string:64>",
  "ApplicationName": "<string:256>",
  "ApplicationVersion": "<version-string:64>",
  "ContentDestinationAsNTPServer": <bool>,
  "AuthenticationTokenURI": [ "<URI:512>", "<URI:512>", ... x 10 ],
  "HTTPSCertificate": [ "<Base64 encoded X509 Certificate:16k>", "<Base64 encoded X509 Certificate:16k>", ... x 10 ],
  "BlobAPIKey": "<Password:64>",
  "BlobAPIUserName": "<UserName:64>",
  "ContainerType": "<mkv | mp4>",
  "FullStoreAndReadSupport": <bool>,
  "WantEncryption": <bool>,
  "PublicKey": "<Base64 encoded PEM RSA PublicKey:2048>",
  "PublicKeyId": "<string:128>"
}

Optional attributes

Changeable attributes

The following attributes can be modified after the initial setup has been completed:

• ConnectionFileVersion

• SiteName

• ApplicationName

• ApplicationVersion

• ContentDestinationAsNTPServer

• AuthenticationTokenURI

• HTTPSCertificate

• BlobAPIKey

• BlobAPIUserName

• WantEncryption

• PublicKey

• PublicKeyId

The Capability API makes it possible for a connected content destination to publish its supported features. The supported capabilities will be published in a JSON file named Capabilities.json , which will be located in the System/ container. To reach the file, the BWS will do a GET request to System/Capabilities.json.

File content

Please note that all capabilities are considered unsupported if the file is missing or wrongly formatted. This is also true if capability isn’t present or set to false. The file is published in a standard JSON format:

{
  "StoreAndRead": {
    "<CAPABILITY1>": <bool>,
    "<CAPABILITY2>": <bool>
  }
}

Connection file

The connection file includes the attribute FullStoreAndReadSupport, typically set for a standard swift content destination, and thus not requiring any configurations of the new capabilities, as they will appear when standard swift commands are supported. In cases where you want to limit what is stored on a swift server, don’t set the new attribute, just enable the capabilities you want to use.

Capability naming

Store is used as prefix when either POST or PUT support is required, while Read is used as prefix when either GET and HEAD support is required. In cases where both are required, they are added as a prefix, i.e. StoreRead.

Current capabilities

• StoreBookmarks

• StoreReadSystemID

• StoreUserIDKey

Implementation details

When responding to a request the Etag header, which contains the md5 hash of the JSON file, must be set, as it used as a checksum. A typical log error from the SCU if cases where the header is incorrect is “object corrupt”.

The Device and user API should be used once one of the following actions are taken by an admin:

• When a user has been registered in the BWM. An object named with the UserID of the user will then be created in the container called Users/. The nice name of the user will be stored as metadata on the object.

• When a user’s nice name is updated. The metadata for that user object will then be updated.

• When a Body worn camera is registered in the BWM. An object named with the BWCSerialNumber of the Body worn camera will then be created in the container called Devices/. The nice name of the device will be stored as metadata on the object.

• When a Body worn camera’s nice name is updated. The metadata for that camera object will then be updated.

A recording will carry the essential information and map it to a UserID and a BWCSerialNumber. . If the information in the recording does not match existing users or devices a 400 Bad Request error response will be returned.

The File upload API is used when the Body worn system uploads a recording created in a Body worn camera. Doing this will create a corresponding recording container, which will get a name according to this template: <UserID>_<BWCSerialNumber>_<TriggerOnTime>..

A recording consists of a list of N video files, where N > 0.

Every clip in the recording corresponds to an object in the container, where the clips are named <StartTime>_<RecordingID>.<ContainerType>. Please note that RecordingID is a short, random number for the recording that shouldn’t be relied upon for identification purposes.

File metadata

The metadata in the Body worn integration API is sent as an HTTP header in the requests. All metadata is presented in strings, while time is specified in UTC. See the Metadata for further instructions.

The Access token API is used by the BWS to retrieve and use a token with the PUT and POST methods. Openstack swift has support for multiple auth systems, one of them being their own Keystone, which is the method that should be used in the Body worn integration API.

Swift security relies on auth tokens being passed with each request. A token is retrieved when the BWS send both an Auth-Key and X-Auth-User in the header of a GET request to the BaseURL, which is supplied by the JSON connection file. The content destination must then respond with an X-Auth-Token and the X-Storage-Url, which are then used during the upload.

All metadata header keys will have the prefix X-Object-Meta or X-Container-Meta as X-<type>-Meta-Key in the HTTP request. All characters will be lowercase except the first letter as well as any letter that follows a hyphen. The values are presented in the URL-encoded UTF8-format, where characters outside of US ASCII and reserved HTTP characters are %XX encoded. Please note that string attributes can’t be larger than 32 bytes except when noted, such as the device name, user name and location attributes, which can be up to 64 bytes. Strings supplied by the user may include any character except control characters. Most applications are expected to accept this, but they may sometimes translate the characters in their individual user interface in cases where they don’t support the full utf-8 set.

Recording container

The name of the container is <UserID>_<BWCSerialNumber>_<TriggerOnTime>.

Bookmark object metadata

The name of the object is bookmark_<Timestamp>_<ID>.

This object is stored only if StoreBookmark capability is set.

The content of the object is the free text description, in utf-8. As there is a timestamp, multiple descriptions can be added. This object can also work as a bookmark. Then the content and all metadata is empty, except for the timestamp.

Video object metadata

The name of the object is <StartTime>_<RecordingID>.<ContainerType>

System container metadata

The container name is System.

This container is created if the StoreReadSystemID capability is set.

System object metadata

Object name is <SystemID>, a UUID.

This object is stored only if the StoreReadSystemID capability is set.

Multiple system objects can exist if several discrete BWS are connected to the same content destination.

All data is stored by the body worn system. Only the SystemName is intended for end user consumption, and can be updated at any time from the body worn system. The ConnectionID is set when the object is created and will never change.

User container metadata

The container name is Users.

User object metadata

Object name is <UserUUID>, an internal UUID

Name is not unique. We recommend that you display Name (UserID).

Devices container metadata

The container name is Devices

Device object metadata

Object name is <BWCSerialNumber>