Onvif Device Reference Design - Getting Started - REST API
Make sure you also check Onvif Device Reference Design's companion project: Onvif device server |
ONVIF Device Reference Design | |
---|---|
Project Architecture | |
|
|
Getting Started | |
|
|
Reference Designs | |
|
|
Customizing the Project | |
|
|
Contact Us | |
|
Contents
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
This reference design is able to mount a REST servers that allow different REST requests.
Get Methods
Link point: /device-information
Gets the information of the device. Type of structure: JSON
Values of the JSON:
- firmware: firmware version of the device.
- type: string
- serial_number: serial number of the device.
- type: string
- hardware_id: hardware ID of the device.
- type: string
- model: model of the device.
- type: string
- manufacturer: manufacturer of the device.
- 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:
- sources: list of JSON's that describes all the sources.
- type: list
The JSON's structure that is inside the sources list is:
- name: name of the video element.
- type: string
- enabled: 1 for enabled, 0 for disabled.
- type: int
- device: source device from which it is captured.
- 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:
- encoders: list of JSON's that describes all the encoders.
- type: list
The JSON's structure that is inside the sources list is:
- name: name of the encoder element.
- type: string
- enabled: 1 for enabled, 0 for disabled.
- type: int
- device: encoder device that is used in the encoding process.
- 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:
- configurations: list of JSON's that describes all the encoders.
- type: list
The JSON's structure that is inside the sources list is:
- c_name: configurations name.
- type: string
- s_name: associated source name.
- type: string
- in_use: 1 if it is in use, 0 in other case.
- 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:
- status: list of JSON's has the status information.
- type: list
The JSON's structure that is inside the status is:
- code: code of the response
- type: int
- description: statys code description.
- 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:
- sources: list of JSON's that describes all the sources.
- type: list
The JSON's structure that is inside the sources list is:
- name: name of the source element.
- type: string
- enabled: 1 for enabled, 0 for disabled.
- 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:
- encoders: list of JSON's that describes all the encoders.
- type: list
The JSON's structure that is inside the sources list is:
- name: name of the encoder element.
- type: string
- enabled: 1 for enabled, 0 for disabled.
- 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:
- c_name: name of the configuration.
- type: string
- s_name: name of the source.
- type: string
- action:action to operate to the configuration. It has two possible values; create and delete.
- 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:
- c_name: name of the configuration.
- type: string
- e_name: name of the encoder.
- type: string
- action:action to operate to the configuration. It has two possible values; create and delete.
- 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:
- enabled: 1 for enabled, 0 for disabled.
- type: string
Example:
{'enabled': 1}
Link point: /configurations/encoders/video
Type of structure: JSON
Values of the JSON:
- c_name: name of the configuration.
- type: string
- e_name: name of the encoder.
- type: string
- action:action to operate to the configuration. It has two possible values; create and delete.
- 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:
- username: username.
- type: string
- username: password.
- type: string
Example:
{"username": username,
"password": password}
It returns a json like:
- sessionToken: unique string assigned for every logged session.
- type: string
{"sessionToken":session_token}
Link point: /validateUser
Validates if a token is still usable.
Type of structure: JSON
Values of the JSON:
- sessionToken: unique string assigned for every logged session.
- type: string
Example:
{"sessionToken": "xsadf8234"}
It returns a json like:
- valid: int that specifies if the session token is valid.
- type: 1 for valid, 0 for invalid
{"valid": 1}