...

3VR's API documentation contains sections for each of the individual APIs. All users should read this overview Overview and the "Getting Started" section, and then proceed to the documentation for their API of choice.

All of the API-specific sections contain information on the format of the request to the appliance and what to expect in return.

The 3VR External System Activity API and the 3VR External Query API also include sample code to demonstrate the format of the
XML request predicate. The 3VR External System Activity API currently includes examples in C# and Java. The 3VR External Query API
has examples in Java and Python. Contact your 3VR representative if you are interested in writing client code in other languages.

The final section contains reference material on the structure of XML-formatting for use in specifying queries and processing the
events returned from queries.

Getting Started

Enabling Web Services

A 3VR VIP Appliance or Enterprise Appliance must have web services enabled in order to accept incoming messages. Enable web services with the following steps:

1. Launch 3VR System Manager.

2. In the Configure panel of System Manager, right-click the name of the appliance and select Start Web Services.

   Image Added

3. A pop up will appear indicating that web services is now running.

Enabling Demand Video Recording

If you plan to create events, set the Enable Demand Video Recording setting to Yes for each camera that will have generic events. This setting will buffer video so it is available for events even if there is not any current motion.

3VR REST API

The 3VR REST API gives client programs access to camera information, system settings, health monitoring data, video, images, and more with HTTP GET requests.

Authentication

The 3VR REST API uses HTTP Basic Authentication and validates against an appliance’s users. This requires an ’Authorization: Basic’ header in the request followed by a base64 encoded user name and password. This request header is case sensitive and must be passed with every request. The format for the user name and password is username:password. As an example, encoding ‘username:password’ to base64 results in ‘dXNlcm5hbWU6cGFzc3dvcmQ=’, and the request header would be the following:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

The server will also provide the challenge required for browser authentication. To test in a browser, navigate to a route and enter a valid user name and password in the dialog that’s displayed. The browser will then handle the authentication call.

All permissions, password constraints, authentication attempt limits, and inactivity limits for users are respected. If a user does not have access to an appliance, channel, view, etc. that information will not be returned in the response. When authentication fails the server will respond with a 401 HTTP status code and a JSON object in the body that includes the ‘AuthenticateResponse’ and a ‘Message’ describing the error. For example:

{ "AuthenticateResponse": "PasswordIncorrect", "Message": "Invalid user name or password" }

The following table lists the possible responses:

...

Port

The 3VR REST API runs on port 8080 and uses SSL, so the server can be accessed via:

https://hostaddress:8080

All exchanges are secured using HTTP BASIC authentication. The user names and passwords must match users that have been added to the 3VR system in System Manager.

Sample Request API

This sample displays the structure of a GET request to an appliance using the 3VR REST API.

In this example, we are requesting a list of system settings, but requests for different information may be made by modifying the path of the request URL (shown in bold text in the following example).

import urllib2, sys
def auth(hostname,username,password):
url = “https://%s:8080/” % (hostname)
password _ mgr = urllib2.HTTPPasswordMgrWithDefaultRealm()
handler = urllib2.HTTPBasicAuthHandler(password _ mgr)
opener = urllib2.build _ opener(handler)
urllib2.install _ opener(opener)
password _ mgr.add _ password(None, url, username, password)
def get _ settings(hostname):
url = "https://%s:8080/settings" % (hostname) #url path to request settings
try:
req = urllib2.urlopen(url)
return req.read()
except urllib2.HTTPError, e:
print "HTTP error: %s" % e.code
except Exception, e:
print e
return ""
if _ _ name _ _ == "_ _ main _ _":
try:
hostname = sys.argv[1]
except:
print "usage: settingsAPI.py [IP address or hostname]"
sys.exit(1)
auth(hostname,"techrep","3MeDeee")
settingsxml = get _ settings(hostname)