ONVIF Device Reference Design - REST API

Introduction

This project provides a REST API that can be used to access different capabilities of the device. This allows you to modify, for example, configurations, sources, and encoders by using REST requests.

Important considerations

We are using Flask as an example of implementations for testing purposes, for commercial implementations, or an implementation exposed to the public, you need to use a server suited for deployment.
The OpenSSL keys used are an example of an OpenSSL implementation, and they should be treated like that, for a final implementation we recommend generating or creating your own keys.

Supported requests

As previously mentioned, this project offers a REST API, these are the current supported requests.

Resources

/device-information

Gets the information of the device. Content type: JSON

GET
Field name	Type	Description
firmware	string	Device Firmware Version
serial_number	string	Device Serial Number
hardware_id	string	Device Hardware ID
model	string	Device Model
manufacturer	string	Device Manufacturer

Example:

GET /device-information


{"firmware": "1.0.0.0",
"serial_number": "123",
"hardware_id": "1",
"model": "model_1",
"manufacturer": "RidgeRun",
}

/sources/video

Get the information of all the video sources. Content type: JSON

GET/PUT
Field name	Type	Description
name	string	Video Source name
enabled	int	1 enabled, 0 disabled

Examples:

GET /sources/video

PUT /sources/video

{"sources":[
{"name":"video1","enabled":1},

{"name":"video2","enabled":1},

{"name":"video3","enabled":1}
]}

/encoders/video

Get the information of all the video encoders Content type: JSON

GET/PUT
Field name	Type	Description
name	string	Video Encoder name
enabled	int	1 enabled, 0 disabled

Examples:

GET /encoders/video

PUT /encoders/video

{"encoders":[
{"name":"h265","enabled":1},

{"name":"h264","enabled":0},

{"name":"mpeg","enabled":1}
]}

/configurations/sources/video

Get information of all the video source configurations Content type: JSON

GET/PUT
Field name	Type	Description
c_name	string	Video Source Configuration Name
s_name	String	Name of the video source to be used by the configuration
in_use	int	Indicates whether or not the configuration is in use
action	string	Action on the configuration. Possible values: create, delete

Examples:

GET /configurations/sources/video


{
            "configurations": [
                {
                    "c_name": "configuration1",
                    "s_name":"video1",
                    "in_use": 1
                },
                {
                    "c_name": "configuration2",
                    "s_name":"video2",
                    "in_use": 0
                },
                {
                    "c_name": "configuration3",
                    "s_name":"video3",
                    "in_use": 1
                },
            ]

        }

PUT /configurations/sources/video


{
  "c_name": "configuration1",
  "s_name":"video1",
  "action": "create"
}

/configurations/encoders/video

Get information of all the video source configurations Content type: JSON

GET/PUT
Field name	Type	Description
c_name	string	Video Encoder Configuration Name
e_name	String	Name of the video encoder to be used by the configuration
in_use	int	Indicates whether or not the configuration is in use
action	string	Action on the configuration. Possible values: create, delete

Examples:

GET /configurations/encoders/video


{
            "configurations": [
                {
                    "c_name": "configuration1",
                    "e_name":"H264",
                    "in_use": 1
                },
                {
                    "c_name": "configuration2",
                    "e_name":"H265",
                    "in_use": 0
                }
            ]
        }

PUT /configurations/encoders/video


{
  "c_name": "configuration1",
  "e_name":"H264",
  "action": "create"
}

/reboot

Reboots the system Content type: JSON

GET
Field name	Type	Description
code	int	Http Error code
description	String	Human readable error description

Example:

{"status": {
              "code": 200,
              "description": "Device has been reboot successfully"
            }
}

/discovery

Enables or disables auto-discover functionality. Content type: JSON

GET/PUT
Field name	Type	Description
enabled	int	0 Discovery disabled, 1 Discovery enabled

Example:

{"enabled": 1}

/login

Logins using the ONVIF user, this returns a bearer token that needs to be used in every request to verify the user. Content type: JSON

PUT
Field name	Type	Description
username	string	User name
password	string	User password

Example:

{"username": "username",
 "password": "password: 
}

Return value:

sessionToken: unique string assigned for every logged session.
- type: string

{"sessionToken":session_token}

/validateUser

Validates if a token is still usable. Content type: JSON

PUT
Field name	Type	Description
sessionToken	string	unique string assigned for every logged session.

Return value:

valid: int that specifies if the session token is valid.
- type: 1 for valid, 0 for invalid

{"valid": 1}

Previous: Getting Started/Evaluating the Project using Docker

Index

Next: Getting Started/Purchasing a License