Onvif Device Reference Design - Getting Started - REST API

ONVIF Device Reference Design
Project Architecture
High Level Design Class Diagrams
Getting Started
Environment Setup Evaluating the Project Evaluating the Project using Docker REST API Purchasing a License
Reference Designs
Customizing the Project
Contact Us

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 mentiones, this project offers a REST API, these are the current supported requests.

Get Methods

Link point: /device-information

Gets the information of the device. Type of structure: JSON

Values of the JSON:

1. firmware: firmware version of the device.
   1. type: string
2. serial_number: serial number of the device.
   1. type: string
3. hardware_id: hardware ID of the device.
   1. type: string
4. model: model of the device.
   1. type: string
5. manufacturer: manufacturer of the device.
   1. type: string

Example:

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

Link point: /sources/video

Get the information of all the video sources.

Type of structure: JSON

Values of the JSON:

1. sources: list of JSON's that describes all the sources.
   1. type: list

The JSON's structure that is inside the sources list is:

1. name: name of the video element.
   1. type: string

1. enabled: 1 for enabled, 0 for disabled.
   1. type: int

1. device: source device from which it is captured.
   1. type: string

Example:

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

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

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

Link point: /encoders/video

Get the information of all the video encoders Type of structure: JSON

Values of the JSON:

1. encoders: list of JSON's that describes all the encoders.
   1. type: list

The JSON's structure that is inside the sources list is:

1. name: name of the encoder element.
   1. type: string

1. enabled: 1 for enabled, 0 for disabled.
   1. type: int

1. device: encoder device that is used in the encoding process.
   1. type: string

Example:

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

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

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

Link point: /configurations/sources/video

Get information of all the video source configurations

Type of structure: JSON

Values of the JSON:

1. configurations: list of JSON's that describes all the encoders.
   1. type: list

The JSON's structure that is inside the sources list is:

1. c_name: configurations name.
   1. type: string

1. s_name: associated source name.
   1. type: string

1. in_use: 1 if it is in use, 0 in other case.
   1. type: int

Example:

{
            "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
                },
            ]

        }

Link point: /reboot

Reboots the system

Type of structure: JSON

Values of the JSON:

1. status: list of JSON's has the status information.
   1. type: list

The JSON's structure that is inside the status is:

1. code: code of the response
   1. type: int

1. description: statys code description.
   1. type: string

Example:

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

Put Methods

Link point: /sources/video

Enables or disables video sources. All video sources cannot be disabled.

Type of structure: JSON

Values of the JSON:

1. sources: list of JSON's that describes all the sources.
   1. type: list

The JSON's structure that is inside the sources list is:

1. name: name of the source element.
   1. type: string

1. enabled: 1 for enabled, 0 for disabled.
   1. type: int

Example:

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

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

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

Link point: /encoders/video

Disables or enables video encoders, not all video encoders can be disabled.

Type of structure: JSON

Values of the JSON:

1. encoders: list of JSON's that describes all the encoders.
   1. type: list

The JSON's structure that is inside the sources list is:

1. name: name of the encoder element.
   1. type: string

1. enabled: 1 for enabled, 0 for disabled.
   1. type: int

Example:

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

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

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

Link point: /configurations/sources/video

Creates a new video sources configuration. Two configurations with the same name cannot exist.

Type of structure: JSON

Values of the JSON:

1. c_name: name of the configuration.
   1. type: string

1. s_name: name of the source.
   1. type: string

1. action:action to operate to the configuration. It has two possible values; create and delete.
   1. type: string

Example:

{
   "c_name": name,
   "s_name": device,
   "action": "create",
}

Link point: /configurations/encoders/video

Creates a new video encoders configuration. Two configurations with the same name cannot exist.

Type of structure: JSON

Values of the JSON:

1. c_name: name of the configuration.
   1. type: string

1. e_name: name of the encoder.
   1. type: string

1. action:action to operate to the configuration. It has two possible values; create and delete.
   1. type: string

Example:

{
   "c_name": name,
   "e_name": device,
   "action": "create",
}

Link point: /discovery

Enables or disables auto-discover functionality.

Type of structure: JSON

Values of the JSON:

1. enabled: 1 for enabled, 0 for disabled.
   1. type: string

Example:

{'enabled': 1}

Link point: /configurations/encoders/video

Type of structure: JSON

Values of the JSON:

1. c_name: name of the configuration.
   1. type: string

1. e_name: name of the encoder.
   1. type: string

1. action:action to operate to the configuration. It has two possible values; create and delete.
   1. type: string

Example:

{
   "c_name": name,
   "e_name": device,
   "action": "create",
}

Link point: /login

Logins using the SOAP user, this returns a bearer token that needs to be used in every request to verify the user. Type of structure: JSON

Values of the JSON:

1. username: username.
   1. type: string

1. username: password.
   1. type: string

Example:

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

It returns a json like:

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

{"sessionToken":session_token}

Link point: /validateUser

Validates if a token is still usable.

Type of structure: JSON

Values of the JSON:

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

Example:

{"sessionToken": "xsadf8234"}

It returns a json like:

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

{"valid": 1}