API endpoints

The body worn content destination API is modeled on the OpenStack Swift API. Only a small subset of Swift is used. The system controller (SCU) is the client; your content destination is the server.

For the full specification and example server, see github.com/AxisCommunications/body-worn-content-destination-api.

Endpoint summary

All endpoints except the auth endpoint require a valid auth token. The auth endpoint requires both a username and key.

Method	Path	Purpose	Success	Errors
GET	/auth/v1.0	Retrieve an auth token	200 OK	401 Unauthorized
GET	/v1/{account}/System/{object}	Retrieve an object and metadata	200 OK	400, 401, 404, 500
PUT	/v1/{account}/{container}	Create a container	201 Created, 202 Accepted	400, 401, 403, 404, 500, 503
POST	/v1/{account}/{container}	Create or update container metadata	204 No Content	400, 401, 403, 404, 500
PUT	/v1/{account}/{container}/{object}	Create an object	201 Created	400, 401, 402, 403, 404, 500, 503, 507
POST	/v1/{account}/{container}/{object}	Create or update object metadata	202 Accepted	400, 401, 402, 403, 404, 500

Error response codes

Code	Meaning
400 Bad Request	The content destination cannot store the recording (permanently). The recording gets status "not transferred" in BWM and becomes available for download. Use when: timestamp out of bounds, clip has no duration, user ID or device ID doesn't exist.
401 Unauthorized	User credentials are invalid or auth token is missing.
402 Payment Required	No more licenses available when attempting to create a BWC or user.
403 Forbidden	User permissions are insufficient for the resource.
404 Not Found	The specific resource is not available.
500 Internal Server Error	Any other server error.
503 Service Unavailable	The content destination is busy but wants the system controller to retry soon.
507 Insufficient Storage	The content destination is out of disk space or disk quota.

API subgroups

The API is divided into these functional areas:

Subgroup	Purpose
Connection API	Set up the connection to the content destination
Capability API	Publish supported capabilities
Access token API	Upload URI and credentials (Keystone-style auth)
Device and user API	Manage devices and users
File upload API	Transfer recordings from body worn system (BWS) to CD

Authentication

The Access token API uses Swift Keystone-style authentication:

1. The SCU sends a GET /auth/v1.0 request with X-Auth-User and Auth-Key headers (from the connection file's BlobAPIUserName and BlobAPIKey).
2. The content destination responds with X-Auth-Token and X-Storage-Url headers.
3. All subsequent requests include the X-Auth-Token header.

Device and user management

The SCU creates objects when users or cameras are registered in BWM:

• When a user is registered: an object named with the UserID is created in the Users/ container. The user's display name is stored as metadata.
• When a BWC is registered: an object named with the BWCSerialNumber is created in the Devices/ container. The device name is stored as metadata.

If recording metadata references a user or device that doesn't exist in the content destination, respond with 400 Bad Request.